---
since: 1.0.0
---

# Configuration Contract

astwire reads its optional configuration from a TOML file:

```text
.astwire.toml
```

discovered by `find_config_upwards()`, which walks from the first target's resolved directory upward until it finds `.astwire.toml` or reaches the filesystem root. If no config file is found, `load_config()` returns `astwireConfig()` defaults.

A missing or unparsable config file is **not** an error — `load_config()` catches any exception from `tomllib.load()` and silently returns defaults.

## Schema consumed by the CLI

```toml
[general]
format = "llm"              # "llm" | "markdown" | "json"
strip_waste = true         # bool
show_tree = true            # bool
output = "context.xml"       # str — output file path

[targeting]
languages = ["python", "javascript", "go"]
skip = [
    "tests/**",
    "migrations/**",
    "docs/**",
]

[ai]
max_tokens = 4000
```

### `[general]`

| Key | Type | CLI equivalent | Default | Notes |
| --- | --- | --- | --- | --- |
| `format` | string | `-f`/`--format` | `"llm"` | Not validated against the allowed set at config-load time; an unrecognized value is normalized to the default (`llm`) by `resolve_format_and_output()` before formatter selection ever runs, and `get_formatter()`'s own fallback also returns `LLMFormatter`. Either path lands on `llm`, never `markdown`. |
| `strip_waste` | bool | `--strip-waste` | `false` | Coerced with `bool()`. |
| `show_tree` | bool | *(no CLI flag)* | `true` | Controls whether `MarkdownFormatter` emits the `## Project Structure` ASCII tree section. There is currently no CLI flag to override this per-run — it is config-only. |
| `output` | string | `-o`/`--output` | `"context.xml"` | Coerced with `str()`. |

Note: `skeleton` has no corresponding key read by the current `load_config()` implementation — `astwireConfig.skeleton` always starts `False` from a config file and can only be set `True` via the `--skeleton` CLI flag.

### `[targeting]`

| Key | Type | CLI equivalent | Default |
| --- | --- | --- | --- |
| `languages` | list of strings | `--lang` | `None` (no filter — all registered languages) |
| `skip` | list of strings | *(no direct CLI flag — patterns only)* | `["tests/", "migrations/", "*.pyc", "__pycache__/"]` |

`languages` is only read if present and a list; `--lang` on the command line overrides it outright rather than merging with it (`main()` only falls back to `cfg.languages` when `--lang` is omitted). Values are language names or extensions, comma-equivalent to `--lang`'s own parsing.

`skip` is consulted by `resolve_named_targets()` (the default, non-`-i` target-resolution path) and, as of SPEC-1.0.md §5 ("skip/ignore win over `-i`"), by `expand_local_imports()` as well — a resolved import target is excluded if it matches `skip`, `.gitignore`, or `.astwireignore`, the same as a plain target would be. See [`../architecture/security-and-privacy.md`](../architecture/security-and-privacy.md) for the full pipeline picture. If `skip` in the file is present but not a list, it is ignored and the default applies.

### `[ai]`

| Key | Type | CLI equivalent | Default |
| --- | --- | --- | --- |
| `max_tokens` | integer | `--max-tokens` | `None` (unbounded — single partition) |

Coerced with `int()`; a non-numeric value is caught and the setting is left unset rather than raising.

## Precedence

For every setting that has both a CLI flag and a config key, `main()` applies:

```python
value = args.<flag> or cfg.<key>
```

This means **CLI flags always take precedence** when both are supplied, and the config file supplies the value only when the corresponding flag is omitted (falsy) on the command line. `--max-tokens` follows the same pattern (`args.max_tokens or cfg.max_tokens`), so `--max-tokens 0` behaves as "not set" and falls back to config, since `0` is falsy.

## `.astwireignore`

Not part of `.astwire.toml` — a separate, sibling ignore file consumed by `IgnoreEngine` (`gitignore.py`), using the same `gitignore` pattern syntax as `.gitignore`. See [`../user-guide/configuration.md`](../user-guide/configuration.md) for usage.

## Related

- [`../user-guide/configuration.md`](../user-guide/configuration.md) — practical guide with worked examples
- [`../architecture/astwire-architecture.md#configuration-precedence`](../architecture/astwire-architecture.md#configuration-precedence) — where config fits in the overall pipeline