# Knowledge Docs > Commit files and research to shared knowledge with a Git-style CLI and API. # Knowledge Source: https://docs.knowledge.abloatai.com/ Knowledge gives people and agents one shared project main, immutable file versions, and a history of who published what. Add documents, review the staged changes, then commit. The browser and API read the same published state. ```sh knowledge add notes.md reports/ knowledge diff --cached knowledge commit -m "Add research and source reports" ``` [Make your first commit](/quickstart), browse the [CLI reference](/cli), or integrate through the [HTTP API](/api). ## Familiar Git behavior Git itself manages the local staging area in `.knowledge`. `add` captures file bytes at that moment; edits made afterward remain unstaged. A Knowledge commit publishes the staged changes directly to shared main. There is no separate push or branch workflow, and any existing `.git` directory is preserved. ## One published main Ablo coordinates publication with a short project claim and guarded transaction. Different file changes can be combined; conflicting edits preserve local work for deliberate resolution. [Recovery](/recovery) explains retries, safe pull, and the distinction between the observed remote head and local files. ## For agents Start with the [agent guide](/agents). The [documentation index](/llms.txt), [complete Markdown reference](/llms-full.txt), and raw Markdown page URLs are available without browser automation. The current CLI is installed from the Knowledge repository; it is not yet a public npm release. Credentials are issued through the web app at `/cli`. MCP and long-lived document claims are planned; these docs describe the CLI/API that exists today. --- # Agent guide Source: https://docs.knowledge.abloatai.com/agents Read [the quickstart](/quickstart.md), then run `knowledge --help` in the installed checkout. The operator supplies `KNOWLEDGE_TOKEN` through the environment. Do not request browser cookies, print credentials, or put them in files you commit. Use the same server origin that issued the credential. ## Read before changing ```sh knowledge status --porcelain knowledge log --json knowledge show HEAD:notes.md ``` Use `clone` to obtain a known baseline for a project with history. Use `init` only for an empty project. Read the actual source documents before changing them; keep source material and derived summaries distinguishable. ## Publish deliberately ```sh knowledge add notes.md knowledge diff --cached knowledge commit -m "Update findings from the source report" ``` Only staged bytes are published. `add -A` also stages deletions; use explicit paths when the operation should only add or update specific documents. Run path commands from the Knowledge checkout root. The printed version receipt confirms publication to main. A local edit, an uploaded blob, or a local Git object does not prove that main changed. ## Recover instead of duplicating If a response is lost, use `knowledge commit --retry`. The saved operation ID and intent survive process restart. Do not generate a replacement operation just because the first request timed out. `commit --abort` is permitted only after a definite rejection; it preserves staged and working files. On conflict, preserve local work and inspect the current version before a new commit. `pull` requires clean tracked files and refuses untracked collisions. Do not bypass it with `git reset --hard` against `.knowledge`. When a commit includes external files the local checkout has not received, pull before staging another change. For direct HTTP integration, keep `operationId`, `expectedHead`, message and changes unchanged across retries. Preserve each upload's `proof`. Identity is resolved from the credential; supplying an `actorId` does not grant authority. See the [HTTP API](/api.md) for exact fields and responses. ## Machine-readable entry points | Resource | Purpose | | --- | --- | | `/llms.txt` | Compact documentation map | | `/llms-full.txt` | Complete plain Markdown corpus | | `/llm.txt` | Alias of the compact index | | `/index.md`, `/quickstart.md`, `/cli.md`, `/api.md`, `/recovery.md`, `/agents.md` | Individual Markdown pages | | `/sitemap.xml` | Public page discovery | These are documentation resources. They do not expose project contents, grant API credentials, or imply that a Knowledge MCP endpoint is available. --- # HTTP API Source: https://docs.knowledge.abloatai.com/api Use `Authorization: Bearer $KNOWLEDGE_TOKEN` against the same HTTPS origin that issued the credential. HTTP is allowed only for loopback development. The CLI refuses redirects, avoiding credential forwarding to a different destination. Browser session authentication continues to work on these same resources. | Request | Result | | --- | --- | | `GET /api/projects/:id/commits?at=` | `{version}` for current main, or null for an empty project | | `GET /api/projects/:id/commits?at=VERSION` | Immutable snapshot, including files and parent ID | | `GET /api/projects/:id/commits` | `{commits}` ordered by parent ancestry, newest first | | `GET /api/projects/:id/files?at=VERSION&path=PATH` | Exact file bytes; query parameters must be URL encoded | | `POST /api/projects/:id/files` | Upload raw bytes with URL-encoded `x-file-path` and `content-type`; returns path/hash/size/mediaType plus upload proof for bearer callers | | `POST /api/projects/:id/commits` | Publish the JSON request below and return the immutable version receipt | | `GET /api/projects/:id/events` | SSE current-head notifications; reconnect and reread after disconnect | | `POST /api/projects/:id/access` | Browser-only, same-origin credential issuance; used by `/cli` | ```json { "expectedHead": "VERSION_USED_AS_BASE", "operationId": "client-generated-unique-id", "summary": "Add research", "changes": [{ "path": "notes.md", "hash": "SHA256_RETURNED_BY_UPLOAD", "size": 42, "mediaType": "text/plain", "proof": "PROOF_RETURNED_BY_UPLOAD" }], "removed": [] } ``` Use an empty expected head for an empty baseline. Reuse the exact operation ID and intent after uncertain failure; a different intent or actor cannot reuse an accepted operation. Upload proof is scoped to account/project/bytes, validated before publication and excluded from stored manifests. Arbitrary account-wide hashes are not sufficient. Author and account come from verified credentials. For restore, send `restoreId` instead of `changes`; the expected head must match exactly. Restore appends a version. Errors carry an `error` message (coordination failures also include their Ablo `code`). Status 400 is invalid input, 401 authentication required, 403 denied upload proof/origin, 404 missing version/project/file, 409 conflict/ownership failure, 413 oversized body and 503 unavailable or uncertain storage outcome. Publication JSON is bounded to 2 MiB. An upload alone never advances main. History is unpaginated in this initial bounded product; SSE is invalidation, not an event-replay guarantee. Shared wire types live in `@knowledge/contracts`. --- # CLI reference Source: https://docs.knowledge.abloatai.com/cli Run commands as `knowledge `. See [First commit](/quickstart) for setup. | Command | Description | | --- | --- | | `init --project ID --url URL` | Connect this directory to an empty project | | `clone ID [directory] --url URL` | Download a project's current main | | `add [-A] ` | Stage current file bytes, like git add | | `status [--porcelain]` | Show staged, unstaged and untracked files | | `diff [--cached]` | Compare working files or staged changes | | `restore --staged ` | Unstage without changing working files | | `rm ` | Stage deletion (Git protects modified files) | | `commit -m MESSAGE` | Publish the staged snapshot directly to main | | `commit --retry` | Resolve/retry the saved pending publication | | `commit --abort` | Discard pending request after a definite rejection | | `pull [--ff-only]` | Update clean local files from main | | `log [--json]` | Read Knowledge commit history | | `show [VERSION[:PATH]]` | Read a version or exact file bytes | ## Authentication and local state Create a project and a 24-hour credential at URL/cli. Set KNOWLEDGE_TOKEN in the environment (never a command argument). KNOWLEDGE_URL can supply --url. Local staging uses Git in .knowledge; commit requires network access. There are no local branches or separate push. Original .git directories are untouched. ## Git behavior Git itself owns the local index and blob snapshots in `.knowledge`. An existing `.git` is left alone. `add` snapshots bytes now; later edits stay unstaged. `diff --cached` shows what the next commit will send, while `diff` shows edits after staging. `restore --staged PATH` unstages without changing working files. `rm PATH` uses Git's modified-file protections and stages deletion. `add -A` stages additions, modifications and deletions; ordinary commits never infer deletion from an incomplete import. `status --porcelain` is native Git porcelain v1. `log --json` emits Knowledge commit metadata; `show VERSION` emits a JSON snapshot; `show VERSION:PATH` emits exact bytes. `HEAD` identifies the locally acknowledged Knowledge version. Run commands taking local paths from the checkout root. Paths are literal; Git pathspec expressions and partial-hunk staging are not exposed initially. The deliberate difference: `commit` publishes directly to shared main and requires a connection. There is no separate push or branch workflow. Printed version IDs belong to Knowledge; internal Git snapshot IDs are local machinery. Main's durable receipt, not a local Git object, proves publication. Git reference: [git-add](https://git-scm.com/docs/git-add) and [basic snapshotting](https://git-scm.com/book/en/v2/Appendix-C%3A-Git-Commands-Basic-Snapshotting). --- # First commit Source: https://docs.knowledge.abloatai.com/quickstart Requires Node 24 and Git. From this repository, run `npm install`, then use `npm exec -- knowledge --help`, or run `node /absolute/path/to/knowledge/apps/cli/bin/knowledge.mjs` from any directory. For the examples below, put `apps/cli/bin` on PATH. This workspace package is not published to npm yet. Create a project in the web app, then visit `/cli` on that same server. Select the project and create a credential. It permits reading and publishing in that project for at most 24 hours. The server rechecks the original sign-in session and account membership on every request. Sign out that session to revoke its delegated credentials; account removal and session-secret rotation also end access. Per-token management and unattended service credentials are subsequent work. Credentials stay out of the checkout and out of Git subprocess environments. ```sh # Paste the credential without echoing it or placing it in shell history. read -r -s KNOWLEDGE_TOKEN export KNOWLEDGE_TOKEN knowledge clone PROJECT_ID research --url https://your-knowledge-server.example cd research # Create or copy your documents into this directory. knowledge status knowledge add notes.md reports/ knowledge diff --cached knowledge commit -m "Add research and source reports" knowledge log knowledge show HEAD:notes.md ``` To attach a directory containing files to an **empty** project, use `knowledge init --project PROJECT_ID --url URL` there, then add and commit. For a project with history, clone first so deletions and edits have a known base. The initial version requires project creation through the web app. --- # Concurrent work and recovery Source: https://docs.knowledge.abloatai.com/recovery Every publication caller, including the existing browser and runner, uses a distinct Ablo participant and a short claim on the project row. The commit carries that claim and the captured head read into the same Ablo transaction. Immutable bytes are uploaded first. The claim covers publication, not an entire editing session: unrelated file preparation remains concurrent. Long-lived document claims, explicit CLI claim commands and automatic renewal across separate CLI invocations are not implemented in this slice. Disjoint changes merge onto main; differing changes to the same file reject. On uncertain failure, run `knowledge commit --retry`. The pending operation ID, message, baseline, uploaded references and staged tree persist on disk, so a new process sends the same intent and receives the original receipt if accepted. Index-changing commands are blocked until that pending operation is resolved. `commit --abort` is allowed only after a recorded definite validation/conflict rejection; it retains staged bytes and working files. It never cancels an unknown remote outcome. To resolve a content conflict, preserve your local changes separately, unstage them, return tracked files to their known baseline, pull the latest version, then reapply and stage a deliberate resolution. `pull` requires a clean tracked tree/index and uses Git's safe two-tree checkout to reject untracked collisions. It never runs `reset --hard`. If publication includes external files absent from the local snapshot, more staging/committing is blocked until pull materializes those bytes. Offline edits remain local. A local `.knowledge/knowledge.lock` prevents concurrent CLI commands from racing over a pending publication. After an abrupt process kill, verify the recorded PID is no longer running before removing that lock and retrying. An interruption during pull may leave safely staged incoming changes; retain the directory and inspect it rather than deleting local work. Automatic process-crash recovery for filesystem materialization is subsequent work. Only regular files are published; symlinks, submodules, escaping paths, Git/ Knowledge metadata and `.env*` paths are refused. `.gitignore` applies to local staging. Limits remain 1,000 files per project and 20 MiB per file. Uploads are sequential and bounded; large-file streaming/resume and watch mode can follow.