CLI reference
Git staging and familiar commands, with commits published directly to main.
Run commands as knowledge <command>. See First commit 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] <paths...> |
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 <paths...> |
Unstage without changing working files |
rm <paths...> |
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 and basic snapshotting.