dctx1.3.1
Reference

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=0

Usage modes · Rust library and publication status

dctx --help

Usage

verbatim
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

verbatim
  -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

verbatim
  template build <PATH>  Compile a template through the facade
  template list          List explicit compiled plans; no home-directory scan

Examples

verbatim
  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_template

Feature and precision limits

verbatim
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

verbatim
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

verbatim
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 --help

Examples on the sample

dctx map find

verbatim
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 --help

Examples on the sample

dctx map neighbors

verbatim
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 --help

Examples on the sample

dctx map explain

verbatim
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 --help

Examples on the sample

dctx map read

verbatim
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 --help

Examples on the sample

dctx map skeleton

verbatim
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 --help

Examples on the sample

dctx map grep

verbatim
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 --help

Examples on the sample

dctx map hubs

verbatim
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 --help

Examples on the sample

dctx map path

verbatim
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 --help

Examples on the sample

dctx map export

verbatim
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 --help

Examples on the sample

dctx languages

verbatim
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 --json

50 languages: 36 full, 8 outline, 6 docs. The table with every tag and file name is on /languages/.

Environment variables

VariableHelp textPrinted by
DCTX_MAX_SOURCE_BYTESDCTX_MAX_SOURCE_BYTES Env: total source bytes one scan may read, 1..17179869184 (default 1073741824 = 1 GiB).dctx map --help
DCTX_MAX_RECORDSDCTX_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_ENTRIESDCTX_MAX_ENTRIES Env: files and directories one scan may visit, 1..100000000 (default 100000).dctx map --help
DCTX_FRESHNESSDCTX_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

CLI-EXIT-CODES.md · full contract
CodeMeaningExamples
0ok: the command answereda find page, including one with no hits; --help
1no result: the command ran, but the named target or input has no answermap 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
2usage: the arguments are wrongan 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
3index 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:

verbatim
token estimate: ceil(2 * UTF-8 bytes / 7) is an estimate, not a tokenizer guarantee.