--- since: 1.0.0 --- # Command Reference astwire has a single-command surface — every feature is a flag rather than a subcommand. ```text usage: astwire [-h] [--targets PATH [PATH ...]] [-i] [--languages] [--lang NAME[,NAME]] [--analysis] [--strip-waste] [--skeleton] [--since REF] [--max-depth N] [--decay-depth N] [--graph] [--max-tokens MAX_TOKENS] [-f {markdown,llm,json}] [-o OUTPUT] [-v] [--uninstall] [targets ...] Dependency-aware context compiler and token tree-shaker. positional arguments: targets Target files or directories to process (default: current directory). options: -h, --help show this help message and exit --targets PATH [PATH ...] Same as positional targets. `astwire --skeleton --targets src/` is valid. -i, --resolve-imports Follow local imports from supported languages (Python, JS/TS, Go). --languages Print the language capability table and exit. --lang NAME[,NAME] Only include these languages (names or extensions, comma-separated). --analysis Dry-run audit displaying recoverable token waste without writing files. --strip-waste Scrub trailing whitespace and collapse empty lines. --skeleton Strip function/method bodies in languages that support skeletonization. --since REF Seed from files changed since this git ref instead of the given targets (tracked + untracked, gitignore-aware). REF is taken as given -- no base branch or remote is auto- detected. Combine with -i to also pull in what the changed files import; without -i, bundles just the changed files. --max-depth N Only with -i: exclude files more than N import-hops from a seed. Manifests (package.json/go.mod) are always kept. No effect without -i. --decay-depth N Only with -i: skeletonize files more than N import-hops from a seed, even without --skeleton. Non-skeletonizable languages still pass through in full, never dropped. No effect without -i. --graph Only with -i: emit a dependency-graph block (edges between bundled files) before the file contents. No-op with a stderr note if used without -i. --max-tokens MAX_TOKENS Ceiling for token budget per output partition. -f {markdown,llm,json}, --format {markdown,llm,json} Output format (default: llm). Inferred from -o extension if omitted. -o OUTPUT, --output OUTPUT Destination context file (default: context.xml). .md/.json/.xml infer format. -v, --version show program's version number and exit --uninstall Completely remove astwire binary and associated local configuration files. ``` ## Targets ```bash astwire # current directory astwire src/ # a directory astwire cli.py # a single file astwire cli.py config.py # multiple targets ``` Defaults to `.` when no targets are given. ## `--targets PATH` Alias for positional targets — useful when another flag would otherwise swallow the path (`argparse` can misparse `astwire --skeleton src/` in some shells; `--targets` sidesteps that). ```bash astwire --skeleton --targets src/ # same as: astwire --skeleton src/ ``` ## `--languages` Prints the language capability table (which extensions are recognized, and which support `-i` import-following and `--skeleton`) and exits immediately — no file discovery or other heavy imports run. ```bash astwire --languages ``` ## `--lang NAME[,NAME]` Restricts the bundle to specific languages after discovery (including anything pulled in by `-i`). Accepts language names or extensions, comma-separated. ```bash astwire src/ --lang python,go astwire src/ --lang ts,tsx,js ``` An unrecognized name is an error; run `astwire --languages` for the supported list. Overrides `.astwire.toml`'s `targeting.languages` outright when both are set. ## `-i`, `--resolve-imports` Recursively discover and bundle local imported modules, starting from each target. ```bash astwire cli.py -i -o context.xml ``` If a target is a directory, every *registered* file under it (any language in the capability table, not just Python) seeds the crawl. From there, only languages with an import engine — Python, JavaScript/TypeScript/TSX, and Go — are traced: local `import`/`from ... import` for Python, relative `./` specifiers for JS/TS, and in-module paths (via `go.mod`) for Go. Standard-library, third-party, and `node_modules`/vendor-style paths are never followed, and imports never escape the project root. See [`../architecture/diagrams.md#2-import-resolution--i---resolve-imports`](../architecture/diagrams.md) for the algorithm. ## `--since REF` Seed the bundle from files changed against `REF` (tracked changes plus new untracked files, gitignore-aware) instead of walking the given targets. Accepts at most one scope path. ```bash astwire src/ --since main -i --skeleton ``` `REF` is always taken exactly as given — astwire never auto-detects a base branch or remote. Requires the scope to be inside a git repository and `REF` to resolve to a real commit; otherwise astwire exits with an error (exit code `2`). Combine with `-i` to also pull in what the changed files import; without `-i`, the bundle is just the changed files themselves. If `-i` is on and `--decay-depth` isn't set explicitly, `--since` implies `--decay-depth 0` (changed files stay full text, everything pulled in via import gets skeletonized). ## `--max-depth N` Only meaningful with `-i` (a stderr note is printed and the flag ignored otherwise). Drops files more than `N` import-hops from the nearest seed. ```bash astwire src/ -i --max-depth 2 ``` Manifests (`package.json`, `go.mod`) are always kept regardless of depth. ## `--decay-depth N` Only meaningful with `-i`. Instead of dropping files past `N` import-hops, skeletonizes them — even without `--skeleton` set. Languages that don't support skeletonization still pass through in full; they're never dropped. ```bash astwire src/ -i --decay-depth 1 ``` ## `--graph` Only meaningful with `-i`. Emits the dependency edges between bundled files as a graph block ahead of the file contents, in whatever output format is selected. ```bash astwire src/ -i --graph -o context.md ``` ## `--analysis` Dry-run audit — prints a token-waste table to stdout, writes no files. ```bash astwire src/ -i --analysis ``` ```text 📊 Token Analysis Report File Path (Relative) Tokens Wasted Waste Lines Waste Bytes Recoverable % ───────────────────────────────────────────────────────────────────────────────────────────── cli.py 1,568 13 16 121 0.83% config.py 556 1 2 4 0.18% ast_crawler.py 1,538 1 1 4 0.07% skeleton.py 490 0 0 0 0.00% ───────────────────────────────────────────────────────────────────────────────────────────── Overall 4,152 15 19 129 0.36% ``` Combined with `-i`, the table gains a **Depth** column (import-hops from the nearest seed; seeds themselves show `0`). The column is omitted entirely when `-i` isn't used. Use this before committing to `--strip-waste` on a large codebase, to see how much is actually recoverable. ## `--strip-waste` Scrub trailing whitespace and collapse consecutive empty lines in the written output. ```bash astwire src/ -i --strip-waste -o context.md ``` ## `--skeleton` Extract symbol signatures (classes, functions, types) and strip implementation bodies to `...`. ```bash astwire src/ --skeleton -o skeleton.md ``` Docstrings, decorators, type annotations, and class structure are preserved — only executable statement bodies inside function/method definitions are removed. Use this to give an LLM the *shape* of a codebase (public interfaces) without the full implementation, at a fraction of the token cost. ## `--max-tokens N` Ceiling for token budget per output partition. When the combined content would exceed `N` tokens, astwire writes multiple numbered files instead of one. ```bash astwire src/ -i --max-tokens 4000 -o context.md # → context_part_1.md, context_part_2.md, ... ``` A single file never gets split across two partitions — if one file alone exceeds `N` tokens, it becomes the sole member of its own (oversized) partition. ## `-f`, `--format {markdown,llm,json}` Output format. Defaults to `llm`. See [`output-formats.md`](output-formats.md) for a full comparison. ```bash astwire src/ -f llm -o prompt.xml astwire src/ -f json -o context.json ``` ## `-o`, `--output DEST` Destination context file. Defaults to `context.xml` (or the `.astwire.toml` `output` value). `-f` always wins for format selection; if `-f` is omitted, a recognized `-o` extension (`.xml`/`.llm`, `.md`/`.markdown`, `.json`) infers the format instead. ```bash astwire src/ -o bundle.md ``` When partitioning is active, each partition's filename is derived from this stem: `bundle_part_1.md`, `bundle_part_2.md`, etc. ## `-v`, `--version` ```bash astwire --version ``` ## `-h`, `--help` ```bash astwire --help ``` ## `--uninstall` ```bash astwire --uninstall ``` Completely removes the astwire binary and associated local configuration files. See [`installation.md#uninstallation`](installation.md) for platform-specific behavior. ## Combining flags All flags compose. A common "give me a tight, dependency-complete, budgeted LLM bundle" invocation: ```bash astwire cli.py -i --strip-waste --max-tokens 6000 -f llm -o prompt.xml ``` This traces `cli.py`'s full internal import closure, strips whitespace waste, caps each partition at 6,000 tokens, and writes minimal XML instead of Markdown. A "review just what I changed, in context" invocation: ```bash astwire src/ --since main -i --graph -o review.md ``` This bundles only the files changed since `main`, pulls in what they import (skeletonized by default, since `--since` implies `--decay-depth 0`), and prepends a dependency-graph section.