CLI reference
Captured from dctx 1.3.1 when this site was built; a check fails the build when the binary prints anything else. Help text is shown verbatim, so it is the CLI's own wording, including the legacy snapshot options it still lists.
What the output looks like#
These are real runs on the tiny kiosk sample, captured by capture.py from the release binary. Commands run inside a copy named kiosk. For source builds, the executable is dctx-cli (or define a dctx alias).
Pack a project#
The header explains the format, the tree assigns IDs, and file blocks carry paths and line counts. The first 40 output lines follow; only the tail is omitted. .env is listed without its contents.
$ dctx pack .
[DCTX_LLM_CONTEXT_SNAPSHOT_V1]
[DIRECTORY:kiosk]
<INSTRUCTIONS>
1. Manifest: The <DIRECTORY_TREE> section lists all files.
- Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID)
- TYPE is [D] for directory, [F] for file.
2. Content Access: To read a specific file:
- Find its UNIQUE_ID from the directory tree.
- Search for the marker: <FILE_CONTENT_START ID="UNIQUE_ID">
- The content is between this marker and </FILE_CONTENT_END ID="UNIQUE_ID">
</INSTRUCTIONS>
<DIRECTORY_TREE>
[D] (ID:ROOT)
[F] .env (ID:F001)
[F] .gitignore (ID:F002)
[F] Cargo.toml (ID:F003)
[F] README.md (ID:F004)
[F] config.toml (ID:F005)
[D] src (ID:D006)
[F] src/main.rs (ID:F007)
[F] src/store.rs (ID:F008)
[F] src/util.rs (ID:F009)
[D] tools (ID:D010)
[F] tools/report.py (ID:F011)
[D] web (ID:D012)
[F] web/app.ts (ID:F013)
[F] web/format.ts (ID:F014)
</DIRECTORY_TREE>
<FILE_CONTENT_START ID="F001" PATH=".env" LINES="0">
[Content omitted by pattern rules]
</FILE_CONTENT_END ID="F001">
<FILE_CONTENT_START ID="F002" PATH=".gitignore" LINES="2">
target/
</FILE_CONTENT_END ID="F002">
<FILE_CONTENT_START ID="F003" PATH="Cargo.toml" LINES="9">
[package]
name = "kiosk"
version = "0.1.0"
edition = "2021"
… (147 more lines)Find a symbol, then read it#
Pass the exact ID from find to read to get its metadata and verified source bytes:
$ dctx map find greet
# kiosk find
s:src/util.rs#greet fn L2-4
s:web/app.ts#renderGreeting fn L10-12$ dctx map read 's:src/util.rs#greet'
# kiosk read
s:src/util.rs#greet fn src/util.rs
pub fn greet(name: &str) -> String {
format!("Hello, {}!", title_case(name))
}For structured consumption, --json puts the same source bytes in source_utf8 (one JSON line, shown verbatim):
$ dctx map read 's:src/util.rs#greet' --json
{"v":2,"place":"kiosk","verb":"read","freshness":{"mode":"strict","state":"verified"},"precision":{"coverage":"syntax","completion":"complete","parser":"dctx-lex-rust/syn-3.0.9"},"records":[{"id":"s:src/util.rs#greet","kind":"fn","path":"src/util.rs","lines":[2,4],"summary":"The greeting shown on the kiosk screen.","summary_source":"doc","signature":null,"span":[44,126],"source_utf8":"pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}","edge":null,"direction":null,"target":null,"confidence":null}],"more":0,"next":null}Pack for a task#
--for uses the task terms to select find results, neighbors and source reads. --budget 800 bounds estimated output tokens, not scan size; the footer reports usage and dropped records.
$ dctx pack . --for 'greet store' --budget 800
# dctx pack --for budget=800 terms=2
## find greet
s:src/util.rs#greet fn L2-4
s:web/app.ts#renderGreeting fn L10-12
## find store
s:src/store.rs#Order struct L4-8
s:src/store.rs#checksum fn L22-24
s:src/store.rs#encode fn L17-19
## neighbors s:src/util.rs#greet
calls:in:s:src/main.rs#main fn src/main.rs L7
calls:out:s:src/util.rs#title_case fn src/util.rs
contains:in:m:src/util.rs module src/util.rs
## neighbors s:src/store.rs#Order
contains:in:m:src/store.rs module src/store.rs
## read s:src/util.rs#greet
s:src/util.rs#greet fn src/util.rs
pub fn greet(name: &str) -> String {
format!("Hello, {}!", title_case(name))
}
## read s:src/store.rs#Order
s:src/store.rs#Order struct src/store.rs
pub struct Order {
pub id: u32,
pub item: String,
pub qty: u32,
}
# end body_tokens=223 budget=800 dropped=0Usage modes · Rust library and publication status
- dctx --help
- General Options
- Template Commands
- Examples
- Feature and precision limits
- dctx map --help
- map
- find
- neighbors
- explain
- read
- skeleton
- grep
- hubs
- path
- export
- languages
- environment
- exit codes
- token estimate
dctx --help
Usage
Usage: dctx <COMMAND> [OPTIONS]
dctx pack [PATH] [--output PATH] [--clipboard] [--json]
dctx pack [PATH] --for <TEXT> [--budget TOKENS]
dctx map <map|find|neighbors|explain|read|skeleton|grep|hubs|path|export> [--json]
dctx context TARGET [--place PATH] [--budget N] [--json] [--session ID --dedupe]
dctx rpc
dctx trace <A> <B> [--max-depth N] [--max-paths N] [--max-bytes N] [--json]
dctx impact <SYMBOL> [--max-depth N] [--max-sites N] [--max-bytes N] [--json]
dctx read <TARGET> [OPTIONS]
dctx languages [--json|--markdown]
dctx doctor [--json]
dctx agent-setup [--format claude|agents|plain]
dctx cache status [--json] [--root PATH]
dctx cache gc [--dry-run] [--root PATH] [--max-bytes N]
dctx cache purge --root PATH [--dry-run] [--yes]
dctx cache purge --all [--dry-run] [--yes]
dctx cache config [auto on|off] [--max-bytes N] [--ttl-days N]
dctx cache auto [--json]
dctx template build <PATH> [--output PATH]
dctx template list [--dir PATH]
dctx plugin search|install|list|info|enable|disable|remove|update|verify
dctx git <status|protect>
`dctx languages` lists every supported language with its tier: full (symbols and call edges), outline (symbols only) or docs (sections).
`dctx rpc` serves the versioned engine protocol for language packages (send hello first; docs/protocol/README.md).
`dctx read` uses `dctx map read`.
Explicit `dctx pack` writes stdout, the clipboard, or `--output`. It does not create a project text file.
`dctx pack --for <TEXT>` prints task context for an agent card instead: map find, neighbors and read of the names in TEXT, cut to `--budget` estimated tokens (default 3000).
`dctx plugin list` and `dctx --help` do not create a project `.dctx/` directory or start a plugin.
`dctx git` routes to the bundled dctx/git plugin. It is not a Git passthrough.
Cache purge requires `--root PATH` or `--all`, and `--yes` unless `--dry-run` is set.
`dctx cache config` shows the persisted policy. `auto on|off` enables auto-clean, `--max-bytes` tightens the system cap, and `--ttl-days` sets idle overlay and preview lifetime.
`dctx cache auto` prints the last auto-clean time, the bytes it reclaimed and the next due time.
`dctx doctor` lists visible binaries, ownership scopes, SHA-256 checksums and cache sizes without changing the cache or using the network.
`dctx agent-setup` prints concise rules to paste into CLAUDE.md or AGENTS.md (default: agents).
pack, map, template, plugin and the TUI run one bounded auto-clean when it is due. They print nothing unless bytes were reclaimed.
`--no-auto-clean` and `DCTX_AUTO_CLEAN=0` disable that slice. `DCTX_CACHE_DIR` selects the cache parent; indexes live in its engine-major.minor subdirectory.General Options
-h, --help Show help
-v, --version Show version
--verbose With --version, also show executable path, scope and limits
Run `dctx pack --help` for pack options and filters.Template Commands
template build <PATH> Compile a template through the facade
template list List explicit compiled plans; no home-directory scanExamples
dctx pack . Pack to stdout and write no project text file
dctx pack . --output out.txt
dctx languages --json
dctx cache status --json
dctx cache gc --dry-run
dctx cache purge --root /path --dry-run
dctx cache config auto off --max-bytes 1000000 --ttl-days 7
dctx cache auto
dctx template build policy.dctx_templateFeature and precision limits
facade_version: 1.3.1
profile: enhanced
wire_version: 2
segment_version: 1
storage: buffered-segments
features: pack,map,templates,fs,segments,cache,syntax-rust
parsers: dctx-structural/3,dctx-lex-js:1,dctx-lex-md:1,dctx-lex-rust/syn-3.0.9
languages: rust,javascript,typescript,python,go,java,c,csharp,kotlin,ruby,php,swift,web,scala,dart,zig,solidity,gleam,fortran,perl,groovy,powershell,elixir,lua,ocaml,r,julia,haskell,erlang,verilog,hcl,sql,clojure,lisp,scheme,elisp,config,shell,make,docker,proto,pascal,graphql,nix,markdown,text,rst,asciidoc,org,tex
unsafe_boundary: syn-dependency
native_code: false
git: false
subprocess: none
precision: the structural extractor reports declarations, imports, headings and conservative calls.
It does not promise exact semantic calls, name or type resolution, or macro expansion.
A syntax-rust build adds syn for supported Rust syntax only, still without type checking.
token estimate: ceil(2 * UTF-8 bytes / 7) is an estimate, not a tokenizer guarantee.
cache cap: 2 GiB hard, 1.5 GiB soft watermark, 1.2 GiB eviction target.
cache ttl: idle overlays and previews 7 days, unpinned roots 30 days, staging 1 day.
auto-clean interval: 1 day.dctx map --help
Usage: dctx map <map|find|neighbors|explain|read|skeleton|grep> <TARGET> [OPTIONS]
dctx trace <A> <B> [--max-depth 1..16] [--max-paths 1..100] [--max-bytes 256..1048576] [--json]
dctx impact <SYMBOL> [--max-depth 1..16] [--max-sites 1..10000] [--max-bytes 256..1048576] [--json]
dctx map hubs [--limit N] [--json] [--place PATH] [--budget TOKENS] [--meta]
Most-called symbols (incoming calls and imports, 1..60 lines, default 20) and per-directory file and symbol counts. No TARGET.
dctx map path <FROM> <TO> [--json] [--place PATH] [--budget TOKENS] [--meta]
Shortest edge path (calls, imports, contains; either direction; at most 8 hops), one `edge:out|in<TAB>id<TAB>kind<TAB>path` line per hop, or `no path`.
dctx map export [--format json|mermaid] [--output PATH] [--place PATH]
The whole graph as one deterministic document (default json: nodes and edges; mermaid: a flowchart of calls and imports). No TARGET, no token cap; --output writes a file.
TARGET Required. map accepts a stable id or a place-relative file.
skeleton takes a file (or m:<path>) and prints its declaration signatures, no bodies,
in source order: id, kind, L<start>-<end>, signature.
A file path is read as m:<path>. Omitting TARGET does not scan.
--json Facade JSON v2, including the precision label
--also DIR Add a read-only root (repeatable); paths and ids carry directory labels
--place PATH Place or worktree root (default: current directory)
--meta Restore the snapshot digest and generation in the text header and the snapshot, generation and age_s JSON fields.
Without it the answer bytes do not change across unrelated edits or time.
--profile Stderr stage timings and the five slowest files. DCTX_PROFILE=1 is the same switch.
DCTX_MAX_SOURCE_BYTES Env: total source bytes one scan may read, 1..17179869184 (default 1073741824 = 1 GiB).
DCTX_MAX_RECORDS Env: files, symbols and edges one index may hold, 1..100000000 (default 1000000). A bigger place is refused while it is scanned.
DCTX_MAX_ENTRIES Env: files and directories one scan may visit, 1..100000000 (default 100000).
DCTX_FRESHNESS Env: strict_live hashes every file on a warm start; the default (stamp) trusts a file whose size, mtime and inode are unchanged and older than 2 s.
--budget TOKENS Output tokens, 1..2000 (explain max: 1000).
Read with no --budget uses the 2,000-token hard cap.
--depth N Map: 1..3; neighbors: 1..4. Explain and read take no depth.
--limit N Map, find and neighbors page size. Explain and read accept only 1.
--offset N Refused. Pass the previous page's next value to --cursor.
--cursor TOKEN Opaque continuation. A stale token is rejected.
--kind fn,type,doc Find kinds
--in PATH Find or grep within a relative path
grep LITERAL Exhaustive literal search of indexed files, hits grouped by enclosing symbol
-i, --ignore-case Grep: ASCII case-insensitive match
--edge calls,imports Neighbor edge filter
--dir in|out|both Neighbor direction
--lines A-B --full Read those absolute source lines inside the node; full permits 400
--rev SHA Refused: this build does not link git
Precision: structural declarations, imports, headings and conservative calls.
Not exact semantic calls, type resolution or macro expansion.
Token estimate ceil(2 * UTF-8 bytes / 7) is not a tokenizer guarantee.
Example: dctx map find 'ignore rules' --json
Example: dctx map map crates/dctx-cli/src/main.rs --depth 2
Example: dctx map map m:crates/dctx-cli/src/main.rs --cursor '<next from the previous page>'
Each verb's own page and example: dctx map <verb> --help
Exit codes: 0 ok, 1 no result (an id not in the index, a binary file), 2 usage, 3 index error; see docs/CLI-EXIT-CODES.md.Map verbs
dctx map map
Usage: dctx map map <TARGET> [--depth 1..3] [--limit N] [--cursor TOKEN] [--json] [--place PATH] [--also DIR ...] [--meta]
Outline of a file (m:<path> or a place-relative path) or a symbol and what it contains.
Example: dctx map map src/lib.rs --depth 2
Every option and its bounds: dctx map --helpdctx map find
Usage: dctx map find <QUERY> [--kind fn,type,doc] [--in PATH] [--limit 1..40] [--cursor TOKEN] [--json] [--place PATH] [--also DIR ...] [--meta]
Ranked symbols, modules, headings and config keys whose name or summary matches QUERY.
Example: dctx map find 'ignore rules' --json
Every option and its bounds: dctx map --helpdctx map neighbors
Usage: dctx map neighbors <TARGET> [--dir in|out|both] [--edge calls,imports] [--depth 1..4] [--limit N] [--json] [--place PATH] [--also DIR ...] [--meta]
Edges of one node: callers with --dir in --edge calls, callees with --dir out.
Example: dctx map neighbors 's:src/lib.rs#run' --dir in --edge calls
Every option and its bounds: dctx map --helpdctx map explain
Usage: dctx map explain <TARGET> [--budget 1..1000] [--json] [--place PATH] [--also DIR ...] [--meta]
One node with its signature and summary, no body.
Example: dctx map explain 's:src/lib.rs#run'
Every option and its bounds: dctx map --helpdctx map read
Usage: dctx map read <TARGET> [--lines A-B] [--full] [--budget TOKENS] [--cursor TOKEN] [--json] [--place PATH] [--also DIR ...] [--meta]
The verified source text of one node; a long node pages with --cursor.
Example: dctx map read 's:src/lib.rs#run' --lines 10-40
Every option and its bounds: dctx map --helpdctx map skeleton
Usage: dctx map skeleton <FILE> [--budget TOKENS] [--json] [--place PATH] [--also DIR ...] [--meta]
Declaration signatures of one file in source order, no bodies.
Example: dctx map skeleton src/lib.rs
Every option and its bounds: dctx map --helpdctx map grep
Usage: dctx map grep <LITERAL> [-i] [--in PATH] [--limit N] [--json] [--place PATH] [--also DIR ...] [--meta]
Exhaustive literal search of indexed files, hits grouped by enclosing symbol.
Example: dctx map grep TODO --in src
Every option and its bounds: dctx map --helpdctx map hubs
Usage: dctx map hubs [--limit 1..60] [--budget TOKENS] [--json] [--place PATH] [--also DIR ...] [--meta]
Most-called symbols and per-directory file and symbol counts. No TARGET.
Example: dctx map hubs --limit 10
Every option and its bounds: dctx map --helpdctx map path
Usage: dctx map path <FROM> <TO> [--budget TOKENS] [--json] [--place PATH] [--also DIR ...] [--meta]
Shortest edge path (calls, imports, contains; at most 8 hops) between two nodes, or `no path`.
Example: dctx map path 's:src/main.rs#main' 's:src/lib.rs#run'
Every option and its bounds: dctx map --helpdctx map export
Usage: dctx map export [--format json|mermaid] [--output PATH] [--place PATH] [--also DIR ...]
The whole graph as one deterministic document. No TARGET, no token cap.
Example: dctx map export --format mermaid --output graph.mmd
Every option and its bounds: dctx map --helpdctx languages
Usage: dctx languages [--json | --markdown]
Lists every language the map index recognises: name, tag, file names, tier and symbol confidence.
Tiers: full = symbols and call edges (lexical, not type-resolved); outline = symbols only, no call edges promised;
docs = headed sections. Confidence `guess` marks heuristic outlines, whose records carry confidence `guess`.
Options:
--json One JSON document with the tiers and the languages
--markdown The README language table
-h, --help Show this help
Example: dctx languages --json50 languages: 36 full, 8 outline, 6 docs. The table with every tag and file name is on /languages/.
Environment variables
| Variable | Help text | Printed by |
|---|---|---|
DCTX_MAX_SOURCE_BYTES | DCTX_MAX_SOURCE_BYTES Env: total source bytes one scan may read, 1..17179869184 (default 1073741824 = 1 GiB). | dctx map --help |
DCTX_MAX_RECORDS | DCTX_MAX_RECORDS Env: files, symbols and edges one index may hold, 1..100000000 (default 1000000). A bigger place is refused while it is scanned. | dctx map --help |
DCTX_MAX_ENTRIES | DCTX_MAX_ENTRIES Env: files and directories one scan may visit, 1..100000000 (default 100000). | dctx map --help |
DCTX_FRESHNESS | DCTX_FRESHNESS Env: strict_live hashes every file on a warm start; the default (stamp) trusts a file whose size, mtime and inode are unchanged and older than 2 s. | dctx map --help |
DCTX_CACHE_DIR | --no-auto-clean and DCTX_AUTO_CLEAN=0 disable that slice. DCTX_CACHE_DIR selects the cache parent; indexes live in its engine-major.minor subdirectory. | dctx --help |
DCTX_AUTO_CLEAN | --no-auto-clean and DCTX_AUTO_CLEAN=0 disable that slice. DCTX_CACHE_DIR selects the cache parent; indexes live in its engine-major.minor subdirectory. | dctx --help |
DCTX_PROFILE | --profile Stderr stage timings and the five slowest files. DCTX_PROFILE=1 is the same switch. | dctx map --help |
Exit codes
| Code | Meaning | Examples |
|---|---|---|
| 0 | ok: the command answered | a find page, including one with no hits; --help |
| 1 | no result: the command ran, but the named target or input has no answer | map read m:nope.py (an id not in the index); map read logo.png (a binary file); pack of a directory with no packable file |
| 2 | usage: the arguments are wrong | an unknown command or flag; a missing target (dctx context with no TARGET); --depth 9; an empty find query; a stale --cursor; m:../outside; a non-UTF-8 argument; cache purge without --root/--all or --yes; a template that does not compile; a bare dctx whose stdin or stdout is not a terminal |
| 3 | index error: the place, source, cache or index could not be opened, read, built or written | --place /no/such/dir; a corrupt or busy cache; a source over DCTX_MAX_SOURCE_BYTES; an --output file that cannot be written; template build /no/such/file (the message names the path) |
Token estimate
Every byte and token count on this site uses the estimate dctx itself prints:
token estimate: ceil(2 * UTF-8 bytes / 7) is an estimate, not a tokenizer guarantee.