---
since: 1.0.0
---

# 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).

## 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`](../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`](../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`](../user-guide/commands.md) for every flag with usage examples, and [`configuration.md`](configuration.md) for the `.astwire.toml` contract that backs these same settings.