CLI reference

Inspect state

Start with diagnostics and the overview. Thread, phase and claim queries explain recorded state; they do not grant write permission. Use --help on a specific command before performing a mutation.

ork doctor
ork maestro --json
ork thread status <thread>
ork phase list <thread>
ork claims list <thread>

Commands by responsibility

Conduction includes thread, phase, modos and gate. Evidence uses claims, verify, fix and retry. Isolation uses worktree and lease. Continuity uses handoff, recall and memory. Delivery uses ship and master. Auditing uses audit and divida.

ork --help
ork ship --help
ork master --help

Integrations and operations

adapter and mcp connect the host. accounts and setup describe runtimes and profiles. sessions, monitor and pulse observe execution and human attention. brain and portfolio access memory and the catalog. fabrica, roadmap and network coordinate work across machines, and projetos shows which project each command reads. grafo queries the local code graph index. The canonical repository reference details each family’s options.

Citable context and human attention

brain context returns entities, parents, citations, freshness and gaps without granting write access. roadmap status builds a read-only report showing where the owner’s attention is needed. master pedir creates a score request for an authenticated human response; it is not an agent-supplied score.

ork brain context --thread <thread> --ids <ids>
ork roadmap status --json
ork master pedir <thread> --formato telegram

Choose the project being read

Every command reads one project, chosen in this order: --projeto <name|path>, anywhere in the command; the ORK_PROJETO variable; in a host without a project directory, the only known project or the projeto.escolha refusal; and, in the terminal, the current directory. An ambiguous or unknown name is refused with the candidates, exit code 4; ork never chooses on behalf of whoever asked.

ork projetos lists the projects known to this machine, without secrets. ork init, ork thread new and ork fabrica entrar register automatically; registrar and esquecer handle older copies without deleting anything from disk. maestro, board, board plan, fabrica and roadmap status start by stating the project read and what was not read.

ork projetos --json
ork roadmap status --projeto meu-produto
ork projetos registrar
ork projetos esquecer <name>

Network, reservations and feature numbers

network roadmap combines the network roadmap from any directory, with typed gaps for anything it did not read. roadmap reservas flags orphaned reservations held by threads already closed on this machine, and --soltar-orfas releases them or passes them to another open thread on the same item, with a record. roadmap feat reserves the next FEAT number through an atomic push; two machines never get the same number, and a reserved number is never reused.

docs sincronizar brings ledger and git facts into roadmap items. --so limits it to the requested items; in the worktree of a thread linked to an item, that item is the default, and --todos covers every item again.

ork network roadmap --json
ork roadmap reservas --soltar-orfas
ork roadmap feat --thread <thread>
ork docs sincronizar --escrever --so RM-NNN

Delivery, CI and concurrency

ci prepare writes .ork-ci/<thread>.json in the thread’s worktree, with its branch; ci run --branch finds that bundle by branch name, fails an ork/* branch without a bundle and, outside a thread, runs only the manifest commands. ship registrar-pr --repo --pr records a PR merged into an external repository declared in ci.external_repositories, with the merge confirmed through the GitHub API and the declared check green on the PR head.

phase run refuses with concurrency.limite, exit code 3, when the project already has max_parallel_threads live sessions in other threads; --esperar waits for a slot. In a session without ledger access, the ork_decision_record MCP tool records the decision through the same contract as decisao registrar.

ork ci prepare <thread>
ork ci run --branch <branch>
ork ship registrar-pr <thread> --repo <owner/name> --pr <n>
ork phase run <thread> GO --prompt "<text>" --esperar

Search memory by meaning

memory search --texto searches the tenant by meaning, combining vector and FTS, and is not deterministic; it cannot be combined with --tags or --thread. memory index maintains the local, idempotent vector index, and --dry-run estimates tokens and cost without calling the provider. memory status --sondar makes one real call and measures its latency.

ork memory status --sondar
ork memory index --dry-run --json
ork memory search --texto "<phrase>" --json

Query the code graph

grafo indexar builds the index for a clean HEAD, in project state and outside git; --verificar extracts again and checks contract, bytes and determinism. vizinhos, chamadores, importadores and caminho answer from the edges, as text or --json, with each edge’s extractor and evidence. status shows the HEAD index, amostra supports manual edge audits and limpar deletes indexes that are not the HEAD of any tree.

Answers are partial by construction: they contain only what the extractor proves, and they say so. With a modified tree, the answer reflects HEAD and warns about it. All of ork grafo needs typescript and micromark installed inside the ork package itself; without them, it refuses with grafo.parser.indisponivel.

ork grafo indexar --verificar
ork grafo status
ork grafo chamadores <symbol>
ork grafo importadores <file> --json
ork grafo caminho <from> <to>