CLI reference
Project and status
| Command | Description |
|---|---|
knowl init [agents...] |
Initialize or upgrade the project and configure selected agents |
knowl upgrade |
Refresh project files, schema, guidance, and .gitignore without agent setup |
knowl status |
Show repository, memory, AI, commit, and workspace status |
knowl doctor |
Check project, vector coverage, agent, and workspace readiness |
knowl state |
Print the active hierarchical project memory |
knowl audit |
Run a read-only, limited integrity audit |
Workspaces
| Command | Description |
|---|---|
knowl workspace init <name> |
Create a workspace |
knowl workspace add <name> [--name <repo-name>] [--default-visibility <repo|workspace>] [--promote-existing] [--force] |
Link the current repository; shares its new writes by default in a linked workspace |
knowl workspace join <manifest> [--name <repo-name>] |
Join from a copied manifest |
knowl workspace list |
List machine-local workspaces |
knowl workspace status [--verbose] |
Show membership and resolved peers |
knowl workspace remove <repo-name> [--export-first] |
Unlink the current repository |
knowl workspace promote [--category <list> | --id <id...>] [--apply] |
Share locally owned knowledge with linked repos. Bare opens a picker; naming flags dry-runs until --apply |
knowl workspace demand [--limit <n>] [--json] |
What the linked repos have queried each other for — the readout that says which knowledge this repo owes its peers |
knowl workspace repin-embedding [--force] |
Repoint the workspace at this repository's embedding profile |
knowl workspace set [--default-visibility <repo|workspace>] |
Change this repo's recorded nature in the workspace manifest |
Memory and retrieval
| Command | Description |
|---|---|
knowl store <content> --category <c> --title <t> [--tag <t...>] [--path <p...>] [--confidence <n>] [--provenance <p>] [--reasoning <text>] [--alternative <text...>] [--source <label>] [--source-commit <sha>] [--supersedes <id>] [--local] |
Record one verified fact, decision or constraint. --local marks it never-publish |
knowl decide [title] [content] |
Record a decision, reasoning, alternatives, and tags |
knowl query [query] [--as-of <timestamp>] [--limit <count>] |
Query current or historically valid project memory |
knowl timeline <item-id> |
Print immutable assertions for one item |
knowl conflicts |
List active exclusive conflict identities |
knowl supersede <item-id> <replacement-id> |
Retire one item in favor of its replacement |
knowl evidence <item-id> |
List evidence and symbol staleness for an item |
knowl context --token-budget <n> [--query <query>] [--task <task>] |
Compose a bounded local context pack |
knowl eval --dataset <path> [--vector] [--json] |
Run a retrieval dataset; --vector enables vector+BM25 evaluation |
knowl access [--json] |
Report highly used, stale, and correction-causing knowledge |
Work loops and sessions
| Command | Description |
|---|---|
knowl task start <title> [-q <query>] |
Start a manual work loop with a focused lookup |
knowl task checkpoint <task-id> <summary> [options] |
Store resumable progress, blockers, artifacts, and verification state |
knowl task finish <task-id> <summary> |
Finish a manual work loop |
knowl task run <title> -- <command...> |
Wrap one bounded command in a work loop |
knowl session start <title> |
Open a bounded, expiring session scratchpad |
knowl session event <id> <type> |
Record one event against an open session |
knowl session finish <id> --status <s> |
Close a session and promote what it earned |
knowl session recover |
Reclaim sessions abandoned by a crashed host |
Skills, code, and optional AI
| Command | Description |
|---|---|
knowl skill list |
List learned skill packages |
knowl skill read <name> |
Read one learned skill package |
knowl skill create <name> |
Create a file-backed skill package and index it |
knowl skill run <name> [args...] |
Run an approved skill package's entrypoint |
knowl skill approve <name> |
Approve a package for execution, pinned to its current contents |
knowl skill revoke <name> |
Withdraw approval, so the entrypoint stops being runnable |
knowl skill trust |
List the packages currently approved to run |
knowl index-code |
Incrementally index TS/JS symbols and import/export edges |
knowl symbols <path> |
Print indexed symbols for one repository-relative file |
knowl synthesize --scope <tag> |
Create or refresh one deterministic tag-scoped understanding |
knowl ask <question> |
Ask a natural-language question using configured AI |
knowl ingest <text> |
Extract and merge knowledge from explicitly supplied text using configured AI |
Data, maintenance, and serving
| Command | Description |
|---|---|
knowl export <path> |
Write portable, checksum-verified JSONL |
knowl import <path> [--dry-run] [--on-divergence newer|skip|theirs|fail] |
Import JSONL with an explicit divergence policy |
knowl snapshot create / knowl snapshot restore <path> --confirm |
Create a checksummed SQLite snapshot, or restore one after verifying its manifest, size, checksum, and SQLite integrity |
knowl config |
Edit configuration interactively |
knowl config get <key> |
Print one configuration value |
knowl config set <key> <value> |
Set one configuration value |
knowl config reset [key] |
Restore one key, or all of them, to the default |
knowl config set-model <model> |
Verify, download and select a custom embedding model |
knowl reindex --vectors |
Prepare the local model and embed items that have no current vector; --force re-embeds every item |
knowl reindex --transcripts [--budget <minutes>] |
Build or update the optional session transcript index; resumable, so a budget is a stopping point rather than a rollback |
knowl park --goal <goal> [--next-action <a>] [--completed <c...>] [--blocker <b>] [--artifact <p...>] [--verified|--unverified] |
Park a workstream and get a key back; hand the key to the user verbatim |
knowl handoff --goal <goal> --next-action <a> [--completed <c...>] [--blocker <b>] [--artifact <p...>] [--verified|--unverified] |
Leave a baton the next session in this project receives once |
knowl resume [key] |
Resume a parked workstream from its key, or list what is parked here |
knowl gc [--apply] [--stale-days N] [--compress-days N] [--min-bytes N] [--ignore-access] [--tombstone-days N] |
Preview or apply duplicate, archive, compression, and tombstone maintenance |
knowl forget-log [--limit N] [--repo <name>] [--json] [--prune-days N] |
Show why knowledge items were destroyed — policy, reason, and the retrieval evidence it overruled — or prune those records |
knowl pr --since <commit> [--dry-run] |
Find drift candidates and, unless dry-run, mark them for review |
knowl view [--port <port>] |
Start the local GET-only viewer |
knowl serve |
Start the stdio MCP server |
knowl agent-event|agent-hook|agent-reminder |
Host-integration commands used by installed lifecycle configuration |