Skip to content

Commands

Swax exposes three subcommands on the swax Click group. All commands share the global --env-file option and the SwaxContext pass object.

Global: --env-file

swax --env-file <path> <subcommand>
  • Default: .env (relative to the current working directory).
  • A missing file is silently ignored — real shell variables still apply.
  • Shell variables take precedence over file values (override=False).

load_env runs in the top-level group callback before any subcommand, so the environment is always populated when a handler runs.

swax init

Initialize a project from a remote spec repository.

swax --env-file .env init

Interactive prompts:

  1. Repository URL — git source of the specifications.
  2. Path to specs inside the repo — the subdirectory to copy.
  3. Local download path — where the specs land in the project.

Internally init writes .swax/config.yml, shallow-clones the repository (depth=1), and copies the specs into the local download path. Configuration is written before cloning so you can inspect it even if the clone fails.

Exit code Cause
0 Success.
1 RepositoryCloneError — Failed to clone <url>: <reason>.
1 SpecsNotFoundError — Specs not found at <path>.

init does not validate SWAX_LLM_* variables — it doesn't need LLM credentials.

swax discover

Rebuild the traceability graph from scratch.

swax --env-file .env discover

Reads .swax/config.yml and the environment (no prompts). Discovers and parses the local specs, runs a two-pass LLM analysis, deduplicates edges, and overwrites .swax/traceability.yml.

Always builds a fresh graph — the existing traceability.yml is ignored.

Exit code Cause
0 Success.
1 MissingEnvironmentVariablesError — Missing env vars: ....
1 SpecParseError — Failed to parse <path>: <reason>.
1 LLMRateLimitedError — LLM rate limited; retry later.
1 LLMCallError — LLM call failed: <reason>.
1 UnsupportedLLMProtocolError — Unsupported LLM protocol: <protocol>.
1 LLMResponseParseError — LLM response parse failed: <reason>.

The command does not retry rate-limited calls and does not log SWAX_LLM_TOKEN.

swax plan

Generate a Markdown Impact Report from spec changes.

swax --env-file .env plan

Reads .swax/config.yml, the environment, and .swax/traceability.yml (produced by swax discover). Parses the local baseline specs, shallow-clones the spec repository fresh, classifies the endpoint diff (added / removed / modified), maps the changed endpoints onto the traceability graph to find transitively affected endpoints, and runs a single-turn LLM analysis.

With no changes, it skips the LLM and prints a LOW-risk "No changes detected" report.

Report sections: Summary, Risk (HIGH / MEDIUM / LOW), Modified Endpoints, Affected Endpoints, Requirements, Checklist.

Exit code Cause
0 Success.
1 MissingEnvironmentVariablesError — Missing env vars: ....
1 SpecParseError — Failed to parse <path>: <reason>.
1 RepositoryCloneError — Failed to clone <url>: <reason>.
1 SpecsNotFoundError — Specs directory not found at <path>.
1 TraceabilityGraphMissingError — Traceability graph not found at <path> — run \swax discover` first`.
1 LLMRateLimitedError — LLM rate limited; retry later.
1 LLMCallError — LLM call failed: <reason>.
1 UnsupportedLLMProtocolError — Unsupported LLM protocol: <protocol>.
1 LLMResponseParseError — LLM response parse failed: <reason>.

See also