Visit djangoplay.org ↗
astwire / API / API Documentation
DocsastwireAPIAPI Documentation

API Documentation

astwire exposes a command-line API through the astwire executable (a compiled Nuitka binary, or the astwire console script when installed from source).

3 min readApplies to v1.0.0
On this page ▾
  1. Entry point
  2. Current command surface
  3. Global options
  4. Positional arguments
  5. Feature flags
  6. Language filtering
  7. Import resolution
  8. Change-scoped seeding
  9. Depth control
  10. Dependency graph
  11. Waste analysis (dry run)
  12. Waste stripping
  13. Skeleton extraction
  14. Token budgeting
  15. Output format
  16. Output destination
  17. Exit codes
  18. Full command reference

Entry point

bash
astwire --help

Current command surface

astwire has no subcommands — every feature is a flag on the single root invocation:

text
astwire [-h] [-i] [--languages] [--lang NAME[,NAME]] [--targets PATH]
        [--since REF] [--max-depth N] [--decay-depth N] [--graph]
        [--analysis] [--strip-waste] [--skeleton]
        [--max-tokens MAX_TOKENS] [-f {markdown,llm,json}]
        [-o OUTPUT] [-v] [--uninstall] [targets ...]

Global options

bash
astwire --version      # print version and exit
astwire --help          # print usage and exit
astwire --uninstall     # remove the binary + local config, exit

--uninstall and -v/--version are handled before any of the heavy analysis modules are imported, and exit immediately.

Positional arguments

bash
astwire [targets ...]

One or more files or directories to process. Defaults to . (current directory) when omitted.

Feature flags

Language filtering

bash
astwire --languages         # print the capability table and exit
astwire src/ --lang python,go

--languages is handled before heavy imports, like --version/--uninstall. --lang filters the discovered set (including anything pulled in by -i) to the given language names or extensions; an unrecognized name is an error.

Import resolution

bash
astwire cli.py -i

Recursively discovers and bundles local (internal) imported modules starting from each target — Python, JavaScript/TypeScript/TSX, and Go. See ../architecture/diagrams.md for the resolution algorithm.

Change-scoped seeding

bash
astwire src/ --since main

Seeds from files changed against REF (tracked + untracked, gitignore-aware) instead of walking targets. At most one scope path; REF is never auto-detected — invalid refs or a non-git scope exit 2.

Depth control

bash
astwire src/ -i --max-depth 2
astwire src/ -i --decay-depth 1

Both require -i. --max-depth drops files beyond N import-hops from a seed; --decay-depth skeletonizes them instead of dropping. Manifests are exempt from both.

Dependency graph

bash
astwire src/ -i --graph

Emits the import edges between bundled files ahead of file contents, in whichever format is selected.

Waste analysis (dry run)

bash
astwire src/ -i --analysis

Prints a token-waste table to stdout and exits. Writes no output file.

Waste stripping

bash
astwire src/ --strip-waste

Strips trailing whitespace, collapses consecutive blank lines, and normalizes line endings in the written output.

Skeleton extraction

bash
astwire src/ --skeleton

Replaces function/method bodies with ..., preserving docstrings, class structure, and type annotations.

Token budgeting

bash
astwire src/ -i --max-tokens 4000

Partitions output across multiple files (context_part_1.md, context_part_2.md, ...) so that no single partition exceeds the given token ceiling. A single oversized file still gets its own partition rather than being split.

Output format

bash
astwire src/ -f json -o context.json

One of llm (default), markdown, or json. See ../user-guide/output-formats.md.

Output destination

bash
astwire src/ -o bundle.md

Defaults to context.xml (or the .astwire.toml output value, if set).

Exit codes

Code Meaning
0 Success (including a successful --analysis dry run, --uninstall, --version, --help)
1 No matching files found under the given targets — including when every matched file was an unregistered language, or --since found changed files but all were filtered out by --lang/skip/.gitignore — or an --uninstall step that requires elevated permissions failed
2 --since misuse: more than one scope path given, the scope isn't inside a git repository, or REF doesn't resolve to a real commit

Full command reference

See ../user-guide/commands.md for every flag with usage examples, and configuration.md for the .astwire.toml contract that backs these same settings.