Last updated 2026-05-07

CLI Configuration

The CLI is configured in three layers, in order of priority: command flags, environment variables, and on-disk config.

Per-workspace config

.stax/config.json in each cloned repo. Read and written via stax config:

stax config                    # print everything
stax config get default-branch
stax config set default-branch main

Recognized keys:

Key	Default	Effect
`default-branch`	`main`	Base branch for `sync`, `land`, `stax test --base`.
`diff-prefix`	(verb-derived)	Override the Conventional-Commit prefix used by `diff`.
`llm-provider`	(auto)	Model used by the title generator. Local-first, opt-in remote.

Environment variables

Variable	Effect
`RUNNER_URL`	Base URL for runner API. Default `http://localhost:4800`.
`STAX_INSTALL_DIR`	Used by `install.sh` only. Default `$HOME/.local/bin`.
`GITHUB_TOKEN`	Authenticates the `gh` CLI for `submit`, and the runner for private actions.

Project registry (`stax test`)

The affected-test runner uses a project registry. Either a registry.toml at repo root, or auto-detection from marker files. See Affected Test Runner for the schema.

State files

Path	What's there
`.stax/features.json`	Feature index for the repo.
`.stax/diffs/`	Per-diff metadata (title, generated description, position).
`.stax/log.jsonl`	Activity log (one JSON line per state-changing command).
`~/.local/share/stax/runner.pid`	Runner PID file used by `runner start/stop/status`.

Resetting

# Wipe the local feature/diff state for the current repo (does not touch git)
rm -rf .stax/

# Stop the runner and forget its PID
stax runner stop || true
rm -f ~/.local/share/stax/runner.pid

# Clear the test cache
stax test --cache-clear