CLI Reference¶

Synopsis¶

occ [directories...] [options]

If no directories are specified, OCC scans the current working directory.

For code exploration, OCC provides a separate namespace:

occ code <find|analyze> ...

For document, spreadsheet, presentation, and table inspection:

occ doc inspect <file> ...
occ sheet inspect <file> ...
occ slide inspect <file> ...
occ table inspect <file> ...

For workspace-level analysis:

occ describe [directories...] ...
occ workspace describe [rootDir] ...
occ workspace analyze [rootDir] ...
occ workspace documents [rootDir] ...

occ [directories...], occ describe ..., occ code ..., the inspect commands (occ doc, occ sheet, occ slide, occ table), and occ workspace ... are separate command families. The default scan accepts positional directories. The describe command accepts one or more directories and reports a fast classification. The code exploration path uses --path <repo-root>, inspect commands target individual files, and workspace commands accept an optional root directory.

Flags¶

Flag Details¶

--by-file / -f¶

Show one row per file instead of grouping by document type:

occ --by-file docs/

--format <type>¶

Choose between tabular (default terminal tables) or json (machine-readable):

occ --format json docs/

--include-ext <exts>¶

Only scan specific file extensions:

occ --include-ext pdf,docx docs/

--exclude-ext <exts>¶

Skip specific file extensions:

occ --exclude-ext xlsx,pptx docs/

--exclude-dir <dirs>¶

Skip entire directories (comma-separated):

occ --exclude-dir node_modules,.git,vendor,build docs/

--no-gitignore¶

By default, OCC respects .gitignore rules. Use this flag to scan all files regardless:

occ --no-gitignore docs/

--sort <col>¶

Sort output rows by a column. Available values: files, name, words, size:

occ --sort words docs/

--output <file> / -o¶

Write output to a file instead of stdout:

occ --output report.txt docs/
occ --format json -o report.json docs/

--ci¶

ASCII-only output with no ANSI color codes, suitable for CI pipelines:

occ --ci docs/

--large-file-limit <mb>¶

Skip files exceeding the specified size in megabytes:

occ --large-file-limit 100 docs/

--structure¶

Extract and display document heading hierarchy. Works with DOCX, PDF, PPTX, ODT, and ODP. Spreadsheets (XLSX, ODS) are skipped since they have no heading hierarchy.

# Tree view of headings per document
occ --structure docs/

# Structure as JSON (includes nodes with character offsets and page mappings)
occ --structure --format json docs/

# Combine with other flags
occ --structure --by-file --no-code docs/

The structure output runs alongside existing metrics — the metrics pipeline is untouched.

--no-code¶

Skip the scc code analysis section entirely:

occ --no-code docs/

--show-confidence¶

Display confidence levels for each metric. In tabular mode, estimated metrics are annotated with a ~ suffix and a footnote is added. In JSON mode, each file row includes a confidence object mapping metric names to "exact" or "estimated":

# Tabular — estimated metrics get a ~ suffix
occ --show-confidence docs/

# JSON — each row includes a "confidence" object
occ --show-confidence --format json docs/

Exit Codes¶

Directory Description Commands¶

occ describe and occ workspace describe classify directories from fast file and manifest signals. They do not parse office document contents and do not run scc.

occ describe .
occ describe ./repo-a ./repo-b --quiet
occ workspace describe --format json

Available flags:

Document Inspection Commands¶

occ doc inspect provides document-specific preflight data for DOCX and ODT files.

occ doc inspect <file>¶

Inspect document metadata, risk flags, content stats, heading structure, and content preview:

occ doc inspect report.docx
occ doc inspect report.docx --format json
occ doc inspect report.docx --sample-paragraphs 10

Available flags:

Current document inspection surfaces:

• document properties (title, author, dates, keywords)
• risk flags (comments, tracked changes, hyperlinks, embedded objects, macros, tables, encryption)
• content stats (words, pages, paragraphs, characters, tables, images)
• heading structure with section codes
• content preview with heading detection
• token estimates (preview and full document)

Spreadsheet Inspection Commands¶

occ sheet inspect provides XLSX-specific preflight data for humans and agents before they serialize workbook contents more deeply.

Common behaviors across the occ sheet namespace:

• the current implementation is XLSX-only
• tabular output focuses on workbook summary, sheet inventory, schema preview, and sample rows
• JSON output exposes a stable command envelope with file, query, and results
• header detection supports auto, none, or an explicit 1-based row number

occ sheet inspect <file>¶

Inspect workbook metadata, per-sheet signals, schema hints, and small row samples:

occ sheet inspect finance.xlsx
occ sheet inspect finance.xlsx --format json
occ sheet inspect finance.xlsx --sheet Revenue --sample-rows 3 --max-columns 10
occ sheet inspect finance.xlsx --header-row none

Available flags:

Current XLSX inspection surfaces:

• workbook properties and custom property count
• visible, hidden, and very hidden sheet counts
• workbook-scoped and sheet-scoped defined names
• formula, comment, hyperlink, merge, and external-reference signals
• per-sheet inferred schema and token estimates

Presentation Inspection Commands¶

occ slide inspect provides presentation-specific preflight data for PPTX and ODP files.

occ slide inspect <file>¶

Inspect presentation metadata, risk flags, per-slide inventory, and content preview:

occ slide inspect deck.pptx
occ slide inspect deck.pptx --format json
occ slide inspect deck.pptx --slide 3

Available flags:

Current presentation inspection surfaces:

• presentation properties (title, author, dates)
• risk flags (comments, speaker notes, hyperlinks, embedded media, animations, macros, charts, tables)
• per-slide inventory (title, word count, notes, images, tables, charts)
• content preview for sample slides
• token estimates (preview and full presentation)

Table Extraction Commands¶

occ table inspect extracts structured table content from DOCX, XLSX, PPTX, ODT, and ODP documents. PDF files return an empty result with an informative note.

occ table inspect <file>¶

Extract table data with auto-detected headers, merged cell handling, and sample row limits:

occ table inspect report.docx
occ table inspect finance.xlsx --format json
occ table inspect finance.xlsx --table 1 --sample-rows 10
occ table inspect report.docx --header-row none

Available flags:

Current table extraction covers:

• DOCX tables via mammoth HTML parsing (colspan/rowspan preserved)
• XLSX sheets treated as tables with merged cell support
• PPTX tables from slide XML (<a:tbl> elements)
• ODT tables from content.xml (<table:table> elements)
• ODP tables from content.xml with per-slide context
• PDF returns tables: [] with a note explaining the limitation
• per-table and total token estimates

Code Exploration Commands¶

occ code keeps the document-scanning command surface unchanged and adds a new on-demand code exploration flow. The strongest support path today is JavaScript, TypeScript, and Python.

Common behaviors across the occ code namespace:

• Relationship queries report resolved, ambiguous, or unresolved status explicitly
• analyze deps groups imports into local, external, and unresolved
• analyze chain can report a chain that is blocked by ambiguity when a path cannot continue confidently
• occ code builds its graph in memory on each run and does not require scc, a database, or a background service

occ code index¶

Build and emit the full codebase index (files, symbols, edges, language capabilities). In JSON mode, outputs the complete index object. In tabular mode, prints a summary line with counts:

occ code index --path .
occ code index --path . --format json
occ code index --path . --format json --output index.json

occ code find name <name>¶

Find code elements by exact name:

occ code find name UserService --path .
occ code find name bootstrap --path . --type function
occ code find name duplicate --path test/fixtures/code-explore --file src/duplicate-a.ts

Use --file when the same symbol name exists in multiple files.

occ code find pattern <text>¶

Case-insensitive substring search across symbol names:

occ code find pattern service --path .

occ code find type <type>¶

List all nodes of a given type (file, module, function, class, variable):

occ code find type function --path .

occ code find content <text>¶

Case-insensitive source-text search:

occ code find content normalize_name --path .

occ code analyze calls <function>¶

Show what a function calls. Receiver-aware resolution is supported for this, super, self, and cls, and ambiguous calls include candidate hints:

occ code analyze calls bootstrap --path .
occ code analyze calls ambiguousCaller --path test/fixtures/code-explore

occ code analyze callers <function>¶

Show what calls a function:

occ code analyze callers createUser --path .

occ code analyze chain <from> <to>¶

Find a call path between two functions. If OCC only finds a path in the opposite direction, it labels the result as a reverse path. When OCC cannot continue because the next hop is ambiguous, it reports a blocked chain instead of silently returning nothing:

occ code analyze chain bootstrap formatName --path . --depth 5
occ code analyze chain ambiguousCaller duplicate --path test/fixtures/code-explore

occ code analyze deps <target>¶

Inspect imports around a file or module. Output is grouped into local modules, external packages, and unresolved imports:

occ code analyze deps src/service --path .
occ code analyze deps src/deps --path test/fixtures/code-explore
occ code analyze deps python/deps --path test/fixtures/code-explore

occ code analyze tree <class>¶

Inspect inheritance for a class:

occ code analyze tree UserService --path .

occ code analyze coupling <target>¶

Show module-level coupling metrics for a directory path. Reports afferent coupling (who imports from this module), efferent coupling (what this module imports), instability ratio, and key classes:

occ code analyze coupling src/code --path .
occ code analyze coupling src/workspace --path . --format json

Shared occ code Options¶

--file is currently supported on find name, analyze calls, analyze callers, and analyze tree.

Workspace Commands¶

occ workspace provides combined analysis of code, documents, and structures in a single versioned JSON payload.

occ workspace analyze [rootDir]¶

Analyze workspace code metrics (via scc), document aggregates, and heading structures:

occ workspace analyze --format json
occ workspace analyze --no-code --format json
occ workspace analyze ./my-project --format json -o workspace.json

Available flags:

occ workspace documents [rootDir]¶

Inspect workspace documents with per-document summaries and cross-reference detection:

occ workspace documents --format json
occ workspace documents --max-files 20 --include-markdown --format json

Available flags:

Environment Variables¶