aac CLI reference

The aac command-line client covers the same MVP workflows as the web console. It is the primary tool for scripting, CI/CD integration, and headless project maintenance.

The CLI is installed with the backend — after pip install -r requirements.txt (or inside the Docker Compose api container) the aac command is available on the shell path.

Configuration

Two pieces of configuration apply to almost every command:

Set both once per shell session, then omit the flags:

export AAC_API_URL=http://127.0.0.1:18000
export AAC_TOKEN=$(aac login --username admin --password 'change-me' --quiet)

Bootstrap: create the first admin

The create-admin command talks to the database directly and is used during first deployment, before any user exists to log in. Run it inside the running API container:

docker compose exec api aac create-admin \
  --username admin \
  --display-name Admin \
  --email admin@example.com \
  --password 'change-me'

Session and project discovery

aac login --username admin --password 'change-me'
aac projects

Sphinx-Needs import

aac import-sphinx \
  --project-id PROJ_001 \
  --file needs.json \
  --version-update-mode automatic_new_version

Version-update modes:

• automatic_new_version — new revisions are created for changed items without prompting
• ask_user — the import pauses on conflicts and waits for decisions submitted via import-decisions

Track a running or waiting import:

aac imports --project-id PROJ_001
aac import-get --project-id PROJ_001 --import-id IMP_042
aac import-decisions --project-id PROJ_001 --import-id IMP_042 --file decisions.json

Validation

aac validation-run --project-id PROJ_001 --mode baseline
aac validation-issues --project-id PROJ_001
aac validation-issue-action --project-id PROJ_001 --issue-id ISS_017 --action suppress --json '{"rationale": "..."}'

Validation modes: baseline, release_gate, import.

Traceability and impact analysis

aac trace   --project-id PROJ_001 --artefact-id ART_001
aac impact  --project-id PROJ_001 --artefact-id ART_001

Suspect state management:

aac suspects --project-id PROJ_001
aac suspect-clear --project-id PROJ_001 --suspect-id SS_007 --rationale "Reviewed and accepted after upstream revision"

Artefact and relationship operations

Reads:

aac artefacts     --project-id PROJ_001
aac artefact-get  --project-id PROJ_001 --artefact-id ART_001
aac relationships --project-id PROJ_001

Writes require the base revision ID (for optimistic-concurrency control):

aac artefact-create --project-id PROJ_001 --file req.json
aac artefact-update --project-id PROJ_001 --artefact-id ART_001 --base-revision-id REV_012 --file req.json
aac artefact-action --project-id PROJ_001 --artefact-id ART_001 --base-revision-id REV_012 --action submit-for-review

Available artefact actions: submit-for-review, mark-reviewed, reject, approve, release.

Baseline and release-gate workflow

aac baseline-create --project-id PROJ_001 --name "Baseline 1" --description "First MVP baseline"
aac release-gate    --project-id PROJ_001 --baseline-id BASE_001
aac baselines       --project-id PROJ_001
aac baseline-action --project-id PROJ_001 --baseline-id BASE_001 --action approve
aac baseline-action --project-id PROJ_001 --baseline-id BASE_001 --action release

Available baseline actions: approve, release, cancel, obsolete.

Authorization for each action follows the same rules as the API — see Authorization. A Quality Engineer token is required to release; a Project Lead token is required to approve.

Reports and job control

aac report --project-id PROJ_001 --report-type traceability_matrix --baseline-id BASE_001
aac reports --project-id PROJ_001
aac report-get --project-id PROJ_001 --report-id RPT_003

Long-running jobs (imports, validation runs, baseline creation, release-gate evaluation, report generation) can be inspected and cancelled:

aac jobs       --project-id PROJ_001
aac job-get    --job-id JOB_099
aac job-cancel --job-id JOB_099

Only the original requester or an Admin may read or cancel an individual job.

Scripting patterns

Chain the MVP flow end-to-end in CI:

export AAC_API_URL=https://aac.internal
export AAC_TOKEN=$(aac login --username "$AAC_USER" --password "$AAC_PASSWORD" --quiet)

aac import-sphinx --project-id "$PROJECT" --file needs.json --version-update-mode automatic_new_version
aac validation-run --project-id "$PROJECT" --mode baseline
aac baseline-create --project-id "$PROJECT" --name "CI $(date -u +%Y-%m-%dT%H:%M:%SZ)"
aac release-gate --project-id "$PROJECT" --baseline-id "$BASELINE_ID"

Combine with aac job-get polling to fail the build if the release gate does not pass.

Related

• Creating a project — before you can run any CLI operations
• Release baselines — the workflow that baseline-create and release-gate implement
• Authorization — which token role is needed for each action