# Command cheat-sheet

Every `occ` command with its canonical one-line description. Run `occ <group>
--help` for the authoritative flag list. Most commands accept `--format
tabular|json`, `-o <file>`, and `--ci`. Machine JSON is compact by default;
the global `--pretty` flag indents it.

## Root

- `occ [directories...]` — Office Cloc and Count: scc-style summary tables for office documents. Flags: `--by-file`, `--structure`, `--quick`, `--include-ext`/`--exclude-ext`/`--exclude-dir`, `--ignore-pattern`, `--no-gitignore`, `--sort files|name|words|size`, `--token-budget <n>`, `--tokenizer`, `--large-file-limit <mb>`, `--no-code`, `--show-confidence`.
- `occ describe [directories...]` — Quickly classify one or more directories from fast file and manifest signals.
- `occ health --format json` — Read the static, append-only feature manifest; builds no index.
- `occ probe [directory]` — Check Git and cache readiness without an index build; grammar and document-parser loading are opt-in with `--grammars` and `--document-parsers`.
- `occ cache prune` — Explicitly remove superseded cache schemas; add `--max-age <days>` and/or `--max-bytes <n>` to bound retained entries.
- `occ atoms --path <repo> [--ref <pin>]` — Stream one resumable, source-body-free work episode for every parent-child Git transition as NDJSON; `--require-complete` gates its footer.

## `occ workspace` — Workspace-level analysis and document context helpers

- `occ workspace describe [rootDir]` — Quickly classify a workspace from fast file and manifest signals.
- `occ workspace analyze [rootDir]` — Analyze workspace code, documents, and structures with a versioned JSON contract. (default JSON)
- `occ workspace documents [rootDir]` — Inspect workspace document summaries and cross-document references. (default JSON)

## `occ doc` — Inspect document structure and content before deep reading

- `occ doc inspect <file>` — Inspect DOCX, PDF, or ODT document metadata, structure, and content preview.
- `occ doc entities <file>` — Extract entities (emails, URLs, dates, phone numbers, mentions) and keywords from a document.
- `occ doc references [directories...]` — Detect cross-references between documents in directories.

## `occ sheet` — Inspect spreadsheet structure and content before deep reading

- `occ sheet inspect <file>` — Inspect XLSX or ODS workbook metadata, sheet inventory, schema, and token estimates.

## `occ slide` — Inspect presentation structure and content before deep reading

- `occ slide inspect <file>` — Inspect PPTX or ODP presentation metadata, slides, and content preview.

## `occ table` — Extract and inspect table content from documents

- `occ table inspect <file>` — Extract structured table data from DOCX, XLSX, PPTX, ODT, or ODP documents.

## `occ code` — Explore code structure (compiler/checker JS/TS + Vue scripts and templates, tree-sitter for 12 more languages)

- `occ code map` — Token-budgeted, importance-ranked repo map (top symbol signatures per file); JSON reports `meta.loadSource` after freshness validation, and an impossible empty envelope returns parseable per-directory narrowing projections.
- `occ code status` — Read entity-cache metadata, freshness, total cache bytes/entries, and superseded roots without building; `--full` explicitly opens/builds the session for complete status. Repeat entity bounds (`--max-commits`, `--max-entities-total`, `--max-total-blob-bytes`) to select the same bounded cache entry.
- `occ code pack` — Token-budgeted, importance-ranked pack (file content, optionally compressed).
- `occ code index` — Build the full codebase index (files, symbols, edges, capabilities).
- `occ code source <name>` — Read one symbol body by node id (`--node-id`) or disambiguated name.
- `occ code doc [name|nodeId]` — Read signature, leading documentation, parameters, and body token price without the body; batch with `--batch` or `--queries-json`.
- `occ code symbol-hash` — Emit the frozen line hash, optional exact-span hash, and verification tiers by stable key; replay an expected tuple for a mechanical verdict. `normalized-equal` is the default token-identity label; `--no-normalized-equal-verdict` restores legacy `cosmetic-drift`, and `--resolve-gone` optionally consults lineage.
- `occ code check <file>` — Check a file's syntax without a language server (exits nonzero only when invalid).
- `occ code dirtree` — Render a bounded directory tree; `--tokens` adds source-spend rollups, `--min-tokens`, `--top`, and map-budget fit.
- `occ code clusters` — Deterministically cluster the resolved local-import graph; returns stable ids, members, cohesion, entry points, cross-cluster dependencies, and explicit coverage/omissions.
- `occ code flows` — Trace bounded deterministic multi-step flows over resolved calls; returns node ids, spans, depth, cluster linkage, cycles, and resolver/frontier honesty.
- `occ code find name <name>` — Find code elements by exact name (`--inline-context`, score-free `--citations`).
- `occ code find pattern <pattern>` — Find code elements by substring pattern.
- `occ code find type <nodeType>` — List all nodes of a given type.
- `occ code find content <text>` — Search code content (full source text).
- `occ code find fused <query>` — Fused search combining name, pattern, and content with rank fusion (`--inline-context`, score-free `--citations`).

Compiler-backed function and method results from `map`, `find`, `index`, and
current-entity commands include parameter and explicit return types in
`signature`.

Code exploration uses a persistent sectioned index outside the repository by
default. Shared flags `--cache-dir` and `--no-cache` select or bypass it; a
fresh full-content entry can serve an excerpt request.

- `occ code analyze calls <fn>` — Show what a function calls (outgoing calls).
- `occ code analyze callers <fn>` — Show what calls a function (incoming calls; optional verified inline context).
- `occ code analyze chain <fromFn> <toFn>` — Find call paths between two functions.
- `occ code analyze deps <target>` — Show module/file import relationships (optional verified inline context).
- `occ code analyze coupling <target>` — Show module-level coupling metrics.
- `occ code analyze tree <className>` — Show class/interface inheritance relationships.
- `occ code seams` — Enumerate cross-module seams (`--since` joins co-change, `--resolve` re-checks keys, `--inline-context` shows a verified reference).
- `occ code facts [predicate]` — List (`--list`) or evaluate capability-gated structural index predicates; read `capabilityGaps`, unresolved-call counts, and coverage before using an absence; layer violations require `--layers <file>`; `--rules <file|->` evaluates user-defined ast-grep rules instead.
- `occ code tsquery` — Run a bounded tree-sitter S-expression query (`--query` or `--query-file <path|->`) and join captures to indexed node ids; scope with `--file <subtree>` and `--lines <start:end>`; opt-in `--budget-early-exit` bounds post-match work; text always ends with capture/file coverage, even at zero hits.
- `occ code pattern` — Match an ast-grep pattern (`--pattern '<code with $META>'`) or rule object (`--rule-file <path|->`) and join matches to indexed node ids; scope with `--file <subtree>`; shares the `--budget-early-exit` bound; text always ends with match/file coverage.
- `occ code ast [file]` — Print a bounded tree-sitter parse tree for a file or `--snippet`.
- `occ code diff` — Show changed symbols for a git diff range (`--range-mode merge-base|exact`).
- `occ code diff --entities` — Compare entity records and emit the authoritative whole-diff CST proof for commits, trees, index, or working tree.
- `occ code diff --entities --file <path> --exit-code` — Restrict the exact Git scope and exit nonzero only for proved whole-diff structural drift; unknown remains zero.
- `occ code diff --obligations` — Add untested logic gaps, touched static seams, and the logic/cosmetic split; `--exit-code` then fails only for a proved gap.
- `occ code diff --fail-on-unknown` — Exit nonzero on unknown whole-diff evidence, and on partial obligation coverage when combined with `--obligations`.
- `occ code history <symbol>` — Show git line history for a symbol.
- `occ code blob-structure` — Read `{requestId, oid, relativePath}` NDJSON requests on stdin and stream body-free declarations and syntactic facts for exact Git blobs; `--require-complete` gates partial/unavailable results.
- `occ code coordinate-verify` — Verify `{ request_id, coordinate }` NDJSON against physical Git blobs and an optional pinned tree without returning source; `--require-complete` gates unavailable checks.
- `occ code graph-export` — Stream observed lineage nodes, explicit import/call module seams, and unified co-change/call/inheritance entity edges for an immutable pin as NDJSON; `--require-complete` gates its footer.
- `occ code entities [query]` — Search durable entities by qualified-name substring (`--fuzzy` for camelCase-aware subsequence matching), kind, file, or directory. JSON uses the measured envelope by default; `--no-envelope` restores the legacy bare array. Entity commands accept `--max-commits`, `--max-entities-total`, and `--max-total-blob-bytes` for bounded first contact.
- `occ code hotspots` — Rank current code entities by logic-change count and source size; filter with `--file`, `--since`, and `--limit`, or add `--page-rank`; honesty reports result omissions, ambiguity, and bounded wide evidence gaps.
- `occ code cochange [entity]` — Rank rename-surviving entity pairs that change logic in the same commits; defaults to `--min-count 3` and reports the same measured honesty signals.
- `occ code drift` — Join unfenced Markdown identifiers (default `--dirs docs/,README.md`) to unique declarations and flag document sections whose last touch predates later proved logic events; `--exit-code` gates only `cst-proved` rows.
- `occ code drift-documents` — Read `{id,content,baseCommit}` NDJSON, resolve references at each pinned baseline without working-tree document reads, and stream positional per-document results plus an honesty footer.
- `occ code anchor [entity]` — Capture one entity as a verifiable memory anchor (durable lineage id + symbol key + hash tuple); `baseCommit` is stamped only when capture proves the committed pairing, and dirty entities degrade to expected-only anchors.
- `occ code verify-anchors` — Read stored anchors as NDJSON and stream one proved verdict per anchor (`fresh|normalized-equal|semantic-drift|moved|renamed|deleted|unknown`); `--strict` gates refusals, `--fail-on-unknown` gates unknowable evidence.
- `occ code impact <entity>` — Traverse dependencies, dependents, and affected tests; `--inline-context` adds verified source and test results include runnable selectors when a runner is identifiable.
- `occ code blame <file>` — Attribute each entity to its latest meaningful change; walks past the indexed window unless `--no-walk-back`.
- `occ code log <entity>` — Follow one entity across commits, renames, moves, and container changes; walks past the indexed window unless `--no-walk-back`.
- `occ code context <entity>` — Build a token-budgeted source bundle around one entity; verified `--inline-context` lines consume that budget, reference-closure counts/handles disclose whether emitted 1-hop targets are closed, open, or unknown, and an impossible empty envelope returns role-based narrowing argv.

## `occ git` — Inspect git changes, history, and churn

- `occ git changed` — List changed files for the resolved diff range.
- `occ git diff` — Summarize or render the resolved diff (`--patch` for a bounded raw patch).
- `occ git history [file]` — Show commit history for a range or file.
- `occ git churn` — Rank changed files by churn.
- `occ git cochange` — Rank file pairs that historically change together (count + lift).
- `occ git capture` — Stream immutable full-DAG repository evidence (commits, per-parent deltas, pinned tree) as NDJSON with a completeness footer; `--require-complete` gates it.

## `occ mcp` — Serve entity intelligence over MCP stdio

- `occ mcp --root <repository>` — Start the non-resident MCP stdio server. Flags: `--cache-dir`, `--exclude-dir` (repeatable), `--tests-dir`, `--no-formats`, `--tokenizer`, `--typescript-checker`, `--no-refresh`, and the index bounds `--max-commits`, `--max-entities-total`, `--max-live-entities`, `--max-total-blob-bytes`, `--max-lineage-events`.

Tools: `occ_doc`, `occ_pattern`, `occ_entities`, `occ_hotspots`, `occ_cochange`, `occ_diff`, `occ_impact`, `occ_blame`, `occ_log`, `occ_context`, `occ_status`, `occ_source`, and `occ_anchor`.

`occ_impact` and `occ_context` accept `inline_context` (non-negative integer,
default 0). It adds verified surrounding source to returned references;
`occ_context` charges those lines to the same hard token budget.

`occ_source` reads one body by exact `nodeId` or a name narrowed with
`relativePath`; it refuses ambiguity and includes source tokens plus measured
freshness and coverage.

`occ_pattern` accepts a `utils` map of named ast-grep utility rules referenced through `matches`.

## `occ skills` — Install and inspect the Agent Skills bundled with occ

- `occ skills install [--agent claude|codex|all] [--user|--project] [--project-root <dir>] [--force] [--link]` — Install occ Agent Skills into one or more coding agents.
- `occ skills list [--format json]` — List the Agent Skills bundled with occ.
- `occ skills path` — Print the path to occ's bundled Agent Skills.
