Visit djangoplay.org ↗
astwire / API / Configuration Contract
DocsastwireAPIConfiguration Contract

Configuration Contract

astwire reads its optional configuration from a TOML file:

3 min readApplies to v1.0.0
On this page ▾
  1. Schema consumed by the CLI
  2. [general]
  3. [targeting]
  4. [ai]
  5. Precedence
  6. .astwireignore
  7. Related
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 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 for usage.