Metadata-Version: 2.4
Name: aac-cli
Version: 0.1.2
Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
Author: Agent Authority Cloud Project
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28
Requires-Dist: cryptography>=42.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-httpx>=0.30; extra == "test"
Dynamic: license-file

# aac-cli — the `aac` platform CLI

The headless operator interface to the AAC control plane (Eng Spec
§XII; Equifax/KPI-6 requirement: every operational task doable without
a web console).

## Install

```bash
pip install aac-cli
```

> **Careful with the name:** `pip install aac` installs an UNRELATED
> project (an MBSE modeling tool that happens to share the acronym).
> The AAC platform CLI's PyPI distribution is **`aac-cli`**; the
> command it installs is `aac` — the awscli precedent (dist name ≠
> command name).

Two personas, two invocation styles:

* **Installed operators** (`pip install aac-cli`) run the bare
  command: `aac tenant register ...`
* **Repo developers** run it through the workspace without installing:
  `uv run aac ...`

The examples below use the bare form; prefix `uv run` if you're in the
repo.

The Python argparse CLI ships the Stage-2 subset of §XII's full command
surface, grown since (B130 trust-anchor, B116 tenant verbs, B170
profiles — which replaced the earlier B116/B117 `aac configure`
family). This Python CLI IS the product CLI — the formerly-planned Go
rewrite was descoped (user ruling 2026-07-23; no separate Go
implementation is coming):

```bash
# B170 — profiles are a first-class resource (CLI Config+Profile
# Spec). `main` is the reserved baseline; `aac configure` is GONE.
aac profile list                   # every profile incl. virtual [main]
aac profile show                   # the SELECTED profile, stored vs effective
aac profile show prod --output table
aac profile create dev --admin-url https://dev-admin.example.com \
    --data-plane-url https://dev-data.example.com
aac profile update main            # materialize/edit the baseline
aac profile delete dev             # local-only; never touches the server

# B154 PR 3 — the tenant id is SERVER-ALLOCATED (canonical
# tnt-<lowercase UUIDv4>; there is no --tenant-id and you never choose
# one). Deployment note: this CLI requires a PR-3+ control plane —
# rollout order + compatibility matrix in RELEASING.md.
# The response prints the id EXACTLY ONCE with the api_key; the
# CLI stores the credential under it AND binds the SELECTED profile to
# it (a bound profile refuses registration — use an unbound one). A
# NAMED profile must exist before it can be selected (§6.1):
aac profile create acme
aac tenant register --profile acme --display-name "ACME Corporation" \
    --contact ops@acme.example \
    --workload-spiffe-id spiffe://acme.com/treasury-agent/v1 \
    --tenant-admin-pubkey-file ./tenant-admin.public.pem \
    --bootstrap-token dev-bootstrap-token-compose-only
# Workload authorities must already be lowercase. The path is
# case-sensitive, so spiffe://acme.com/Treasury-Agent is valid and is
# preserved exactly; spiffe://ACME.com/treasury-agent is rejected.
# If the response is lost, retry the exact frozen request with no stable
# arguments. The selected profile supplies its AAC-managed recovery state:
aac tenant register --profile acme
# Registration is a gated ceremony (Eng Spec §XVII.6): the control
# plane rejects it unless X-AAC-Bootstrap-Token matches its
# AAC_CP_BOOTSTRAP_TOKEN. --bootstrap-token falls back to
# $AAC_BOOTSTRAP_TOKEN (note: the CLI-side env var has no CP_ — the
# server-side name AAC_CP_BOOTSTRAP_TOKEN is NOT read by the CLI).

# B142 — developer-tier SELF-SERVE registration (no ceremony token):
# sign in with GitHub or Google; your verified identity becomes the
# tenant's first tenant-admin. Needs a deployment with self-serve
# enabled + a shared connection for the family.
aac profile create dev        # (re)create it — deleted in the B170 example above
aac tenant register --profile dev --display-name "ACME Dev" \
    --contact dev@acme.example --idp github
aac sso login --profile dev            # thereafter: plain login

# B116 — admin-surface tenant inspection + attribute update.
# Tenant ids are the server-allocated canonical tnt-<uuid> form
# (B154 PR 5) — captured at registration / shown by `aac profile show`.
aac tenant list                                # which tenant ids exist (no 409 probe)
aac tenant describe --tenant-id tnt-<uuid>     # workloads + key METADATA
aac tenant update --tenant-id tnt-<uuid> --display-name "ACME Manufacturing Inc"

# B121/B228 — business-domain control proof and bounded claim lifecycle.
# Registration can capture up to 16 pending rows with repeatable --tenant-domain.
# The issue/verify/release/revoke commands
# require the owning tenant's tenant-admin session and default --tenant-id from
# the profile; the established tenant describe command keeps its explicit id.
aac tenant register --display-name "ACME" --contact ops@acme.example \
    --tenant-domain acme.example
aac tenant issue-domain-challenge --domain acme.example
# Publish the exact record printed above, then:
aac tenant verify-domain --domain acme.example
# B182 keeps verification and binding explicit. The binding command consumes
# current exact-name evidence (and lazily revalidates when due); verify-domain
# never performs an implicit binding write.
aac tenant bind-trust-domain --trust-domain acme.example
aac tenant list-trust-domains --output table
aac tenant describe --tenant-id tnt-<uuid> --output table  # status + TXT
aac tenant release-domain --domain acme.example --reason "planned transfer"
aac tenant revoke-domain --domain acme.example --reason "DNS control incident"

# If bind-trust-domain reports missing proof, its printed issue/verify/rerun
# commands pin the selected profile, effective admin URL, tenant id, and exact
# domain. They never print a session, bootstrap token, or challenge value.

# B153 — replace the tenant-admin key. Accepts and transmits the PUBLIC half
# ONLY. It never generates or writes private-key material, and it refuses a
# private key without transmitting or logging it — it does read the file you
# name, because refusing requires inspecting it.
# Replacement is IMMEDIATE and forward-only: the previous key stops
# verifying ingest JWSs at once (admin keys get NO grace window) and can
# never be reinstated.
openssl genpkey -algorithm ed25519 -out tenant-admin.pem
openssl pkey -in tenant-admin.pem -pubout -out tenant-admin.public.pem
aac tenant rotate-admin-key --tenant-admin-pubkey-file tenant-admin.public.pem
# BEFORE running it in production: stage the new PRIVATE key on the
# trust-anchor publisher host and be ready to restart it. The restart
# procedure DIFFERS by deployment path — a Docker publisher's env and key
# bind-mount are fixed at container creation, so a plain restart comes back
# on the OLD key. Follow trust_anchor_publisher/INSTALL.md, "Rotating the
# tenant-admin key". Publication stays paused until it restarts.
# --bootstrap-token (or $AAC_BOOTSTRAP_TOKEN) lets a ceremony operator
# rotate for a tenant that has no session.

# B172 — post-registration workload lifecycle. --tenant-id is optional
# here: the selected profile supplies it by default. JSON is default;
# every command also supports --output table.
aac tenant add-workload --spiffe-id spiffe://acme.com/payroll/v1 \
    --display-name "Payroll"
aac tenant list-workloads                       # ACTIVE only
aac tenant list-workloads --all                 # + DEACTIVATED history
aac tenant describe-workload --workload-id <opaque-id>
aac tenant update-workload --workload-id <opaque-id> \
    --display-name "Payroll v2"
aac tenant update-workload --workload-id <opaque-id> --clear-display-name
aac tenant deactivate-workload --workload-id <opaque-id> \
    --reason "service retired"
# Deactivation is terminal; there is no delete/reactivate command, and
# the exact SPIFFE ID remains globally reserved.

aac chain show --token-id <64-hex token or chain root> --tenant-id tnt-<uuid>
aac chain show --token-id <id> --output table
aac chain show --token-id <id> --render --render-out ./aeg.html   # headless
aac chain show --token-id <id> --render --open                    # + browser

# B130 — YOUR tenant's trust-anchor state (what .well-known never
# shows: REVOKED keys, expired-grace history, lifecycle timestamps,
# tenant-admin key status, the ingest ledger). Bearer-authenticated;
# tenant scoping is implicit in the credential.
aac trust-anchor list --tenant-id tnt-<uuid>        # both roles, all states
aac trust-anchor list --role tenant-admin           # ingest-signing keys only
aac trust-anchor describe --kid key-1               # lifecycle + public PEM
aac trust-anchor ingest-history --artifact-class root-keys --limit 20
# Session-only emergency/environment-retirement operation. Terminal, may
# revoke the last root, and cannot be authorized by bootstrap token/API key:
aac trust-anchor revoke --tenant-id tnt-<uuid> --kid key-1 \
    --reason "root signing key suspected compromised"

# B144 — before the first tenant IdP, Tenant Ops generates an Ed25519
# offline recovery keypair. The private PEM stays offline and mode 0600;
# only the non-secret enrollment JSON crosses to AAC Ops/control plane.
aac sso generate-idp-recovery-key \
    --private-key-file offline-idp-recovery-private.pem \
    --enrollment-file idp-recovery-enrollment.json
aac sso enroll-idp-recovery-key \
    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
    --file idp-recovery-enrollment.json \
    --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"

# B140 — register a tenant↔IdP connection (Eng Spec §XVII.4; the sso
# noun). The connection config rides as a JSON file (nested claims
# mapping — see --help for an Entra example). Initial recovery-key
# enrollment above happens before first-IdP registration. First-IdP
# registration is the ops ceremony; later IdPs ride a cached session:
# (--tenant-id takes the canonical tnt-<uuid> id captured at your
# tenant's registration — B154 PR 5: a dotted value fails locally.)
aac sso register-idp --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
    --file connection.json \
    --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"

# B151 — discover the opaque connection id and current revision without a
# session. The public response contains only safe issuer metadata, a stable
# idp_connections.id, and the numeric ETag needed for correction:
aac sso list-idp --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000

# B151 — correct the COMPLETE connection document. Pin the revision you
# reviewed; the CLI sends it with the cached tenant-admin session and never
# substitutes a newer revision. Repeating after a lost response is safe:
aac sso replace-idp --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
    --connection-id <id-from-list-idp> \
    --revision <revision-from-list-idp> \
    --file corrected-connection.json

# B144 — if the IdP is unavailable, the same B151 replacement is authorized
# by a three-command two-party ceremony. Tenant Ops signs the exact corrected
# file and receives a request id plus REPAIR-INTENT fingerprint. AAC Ops
# compares both through the incident channel, approves that exact intent, and
# manually notifies Tenant Ops. Tenant Ops then runs replace-idp with the same
# request/file/revision/key. The CLI internally redeems a ten-minute,
# single-use capability, holds it only in memory, and never prints or stores it.
# It grants no login, data-plane access, or general administration.
aac sso request-idp-repair \
    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
    --connection-id <id-from-list-idp> \
    --revision <revision-from-list-idp> \
    --file corrected-connection.json \
    --recovery-key-file offline-idp-recovery-private.pem
aac sso approve-idp-repair \
    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
    --connection-id <id-from-list-idp> \
    --repair-request-id <tenant-provided-request-id> \
    --repair-intent-fingerprint sha256:<tenant-provided-intent-hash> \
    --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"
aac sso replace-idp \
    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
    --connection-id <id-from-list-idp> \
    --revision <same-request-revision> \
    --file corrected-connection.json \
    --repair-request-id <approved-request-id> \
    --recovery-key-file offline-idp-recovery-private.pem

# These fingerprints are different: recovery_key_fingerprint identifies the
# enrolled Ed25519 PUBLIC key; repair_intent_fingerprint identifies one exact
# tenant/connection/revision/document/key intent. Neither replaces the other.

# Recovery-key lifecycle is normal-session administration. Generate a fresh
# pair before rotation; old material cannot return. Revocation is terminal.
aac sso list-idp-recovery-keys --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
aac sso rotate-idp-recovery-key \
    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
    --file new-idp-recovery-enrollment.json \
    --replaces-recovery-key-id <current-active-key-id>
aac sso revoke-idp-recovery-key \
    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
    --recovery-key-id <current-active-key-id> \
    --reason "offline media lost"

# B142 — register a SHARED developer-tier connection (platform
# operator ceremony ONLY; owned by no tenant). GitHub registers with
# jwks_static {"keys": []} + explicit endpoints (GitHub is not an OIDC
# provider); Google registers via discovery + public_client_secret:
aac sso register-idp --shared --file shared-github.json \
    --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"

# B141 — sign in via your tenant's IdP (aws sso login semantics).
# Device flow by default (the browser can be on ANY machine — headless
# friendly); Google-family connections use loopback PKCE (Google's
# device grant is scope-restricted). Success caches a short-lived AAC
# session token AND writes the config profile in one motion; every
# admin verb (tenant list/describe/update, self-serve register-idp)
# then rides the session automatically.
aac sso login --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
aac sso login --issuer https://login.microsoftonline.com/<tid>/v2.0  # >1 IdP
aac sso login --flow pkce --no-browser        # print the URL, don't launch

# Sessions are REFRESH-LESS by design (Eng Spec §XVII.2): on expiry
# any admin verb tells you to re-run `aac sso login` — there is no
# refresh token to steal, and no silent re-authentication.

# B155 — session niceties (cache-file operations; the CLI never
# parses the token itself). whoami exits 0 = live, 3 = expired/none (§14).
aac sso whoami --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
aac sso logout --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
```

Naming: console script = `aac` (the §XVI-reserved name); import
package = `aac_cli` (the SDK owns the `aac` import package);
distribution = `aac-cli` (decided at first release, B119: bare `aac`
on PyPI belongs to an unrelated active project and is not claimable).

## Configuration

Profiles live in `~/.aac/config` (UTF-8 INI with DIRECT sections —
`[main]`, `[dev]`, `[prod]`, never `[profile dev]`; override the
directory with `AAC_CLI_HOME`). `aac profile create/update` are the
writers; the file stays hand-editable INI, but note a rewrite does not
preserve comments (aws-cli behaves the same):

```ini
[main]
admin_url = http://127.0.0.1:8000
data_plane_url = http://127.0.0.1:9000
tenant_id = tnt-550e8400-e29b-41d4-a716-446655440000

[dev]
admin_url = https://dev-admin.example.com
data_plane_url = https://dev-data.example.com
```

**`main` is the reserved baseline profile.** It always exists —
virtually (built-in localhost defaults) until `aac profile update
main` materializes it — and cannot be created or deleted. Profile
SELECTION for operational commands is `--profile <name>` >
`AAC_PROFILE` > `main`; a selected profile that doesn't exist is an
error, never a silent fallback. Prototype-era `[default]` sections
migrate to `[main]` automatically on first touch (both-exist-and-
differ fails closed with manual remediation).

**`tenant_id` is system-managed.** Profile commands display it but
never prompt for or accept it — only authenticated workflows
(`aac tenant register`, `aac sso login`) write it. Canonical
`tnt-<uuid>` validation is MANDATORY (B154 PR 5): a profile holding a
prototype-era dotted value (`acme.com`) now fails every command, exit
3, with remediation printed (delete the stale `tenant_id` line, then
re-register or `aac sso login` to bind a canonical id).

Setting precedence within the selected profile: flag > env
(`AAC_ADMIN_URL` / `AAC_DATA_PLANE_URL` / `AAC_TENANT_ID`; also
`AAC_BOOTSTRAP_TOKEN` for `tenant register --bootstrap-token`) >
profile > localhost defaults. `aac profile show` prints stored AND
effective values with each one's source (`flag` / `env:AAC_*` /
`profile:<name>` / `default` / `unset`).

Guardrails (deliberate bounded complexity): at most 50 profiles
including `main`, 50 keys per section, 30-character keys, and
512-character values — exceeding any is a deterministic exit-3
invalid-config error. Unknown keys are preserved by writes and
reported (by name) by `aac profile show`.

`~/.aac/state/tenant-registrations/<profile>.json` is AAC-managed
registration recovery state (one record per profile; dir 0700, file
0600). Do not edit, rename, copy between profiles, or delete these
files while a registration is unresolved — deleting one cannot cancel
a request that may already have committed. A profile with such a
record cannot be deleted. `aac tenant register` creates the record before
authentication or HTTP and holds a nonblocking per-profile process lock across
the entire attempt. A transport interruption retains the same request id and
frozen stable intent; a bare retry resumes it with fresh ceremony/evidence
credentials. Supplying identical stable arguments is also accepted, while a
difference fails locally before network access. The CLI deletes pending state
only after success is safely persisted or the server returns the exact paired
`Idempotency-Key` + `AAC-Registration-Status: not_created` guarantee.

B183 applies the same canonical workload-ID boundary before either a durable
registration-state write or an add-workload network request: a non-lowercase SPIFFE
authority is rejected, never normalized. An accepted path retains its exact
case in the frozen stable intent, fingerprint input, state file, and every
retry comparison.

A completed server recovery returns tenant identity but cannot replay the
one-time API key. The CLI binds the profile and transitions the state to
`completed_credential_reissue_required`, directing the operator to the
separate B173 reissue capability; B171 does not implement reissue.

### Replace or recover a tenant API key (B173)

After establishing an own-tenant `tenant-admin` session, run:

```console
aac tenant reissue-api-key \
  --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
  --profile production
```

This is immediate replacement, not B98/B189 graceful rotation: the server
revokes every ACTIVE tenant API key and returns one fresh `aac_ak_*` value once.
The CLI makes one HTTP request per invocation and atomically replaces the
mode-`0600` credential file only after validating the complete success
response. A transport interruption leaves the local file untouched and tells
the administrator to run the command again; the next explicit invocation is a
fresh attempt that revokes any unknown prior result. There is no automatic
retry or secret-response journal. A successful B173 replacement also removes
any superseded non-secret B189 local rotation record. It does not silently
delete the separate staged key file; that value is now revoked and must be
removed through the approved secure-file procedure.

After success the CLI prints copy/paste-ready `aac trust-anchor list` and curl
commands for API-key-only verification against `GET /v1/trust-anchors`. The
curl recipe streams the stored credential through stdin configuration rather
than writing plaintext into shell history or an OS process argument.

Operator-assisted onboarding recovery is exceptional and requires both the
explicitly opened bootstrap ceremony and the matching completed registration
locator. Load `AAC_BOOTSTRAP_TOKEN` through the approved secret-handling
process, then run:

```console
aac tenant reissue-api-key \
  --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
  --registration-request-id treq-550e8400-e29b-41d4-a716-446655440000 \
  --profile onboarding
```

The server admits this only before a tenant login path exists. The `treq-*`
value is a locator, never a credential. Tenant API keys are separate from
tenant-admin Ed25519 keys and B144 offline IdP-recovery material. See
**SOP-010 — Recover or replace a tenant API key** in the AAC design vault's
`sops/` directory for the tenant-administrator and AAC Ops procedures.

### Rotate a tenant API key without downtime (B189)

Planned rotation uses a nested command family and an own-tenant
`tenant-admin` AAC session:

```console
aac tenant api-key list --profile production
aac tenant api-key issue --profile production
```

`issue` saves a non-secret `akr-*` issuance identity before sending one HTTP
request. It writes the returned plaintext only to a new mode-`0600` staged
file (default `~/.aac/credentials/<tenant-id>.next`), refuses existing files
and symlinks, requires any custom parent directory to exist, preserves that
directory's permissions, and never replaces the current profile credential. Its success
output contains metadata and a curl recipe that reads the staged file without
putting plaintext in shell history or process arguments.

Move every client to the staged key through the approved secret store, verify
client traffic, then list again and select the old key by its exact non-secret
`key_id`:

```console
aac tenant api-key retire \
  --key-id ak_0123456789abcdef \
  --yes \
  --profile production
```

Retirement requires two ACTIVE keys and is terminal. The CLI fetches the
authoritative set immediately before the request, names the exact key that will
remain, and never guesses by age or position. It does not silently promote the
staged file into the current credential location. Do that only through the
approved local secret-handling procedure after the selected old key retires.

If an issue response is ambiguous, rerun the same command. The saved identity
is reused: a non-committed attempt may return the new plaintext, while a
committed attempt reports that plaintext is unavailable and identifies the
unknown new row through `api-key list`. Retire that unknown row, leaving the
known old credential ACTIVE, then issue again. No automatic retry or plaintext
journal exists. A profile with unresolved rotation state cannot be deleted.
See **SOP-011 — Rotate a tenant API key without downtime** in the design vault.

`~/.aac/idp-repair-requests/<tenant_id>/<connection_id>.json` is B144's
separate AAC-managed IdP repair record (directory 0700, file 0600). It is
written before `request-idp-repair` transmits anything and contains the exact
connection document, document digest, request id, recovery-key fingerprint,
and public signature. It contains neither the offline private key nor the
short-lived AAC repair capability. An identical retry reuses the request id;
a different live intent is refused locally. Preserve this file with the
incident until replacement is complete, and do not edit, rename, copy between
tenants, or delete it to “cancel” a request that may already exist server-side.

### `AAC_CLI_HOME` — isolated homes

`AAC_CLI_HOME` relocates the whole `~/.aac` tree (config +
credentials). Two everyday uses:

```bash
# 1. Throwaway smoke/test home — nothing touches your real config:
AAC_CLI_HOME=/tmp/aac-smoke aac tenant register --display-name "Smoke" ...

# 2. Multi-account operators — hard-wall separation beyond profiles
#    (separate credential files, not just separate config sections):
alias aac-prod='AAC_CLI_HOME=$HOME/.aac-prod aac'
alias aac-staging='AAC_CLI_HOME=$HOME/.aac-staging aac'
```

Profiles share one credentials directory; `AAC_CLI_HOME` gives each
context its own.

Credentials — TWO kinds coexist in `~/.aac/credentials/` (documented
coexistence, Eng Spec §XVII.9):

* `{tenant_id}` — the bare `aac_ak_...` string at mode 0600, written
  by `aac tenant register` (the key is printed EXACTLY ONCE — only its
  peppered hash exists server-side) and presented as `Authorization:
  Bearer` by the DATA-PLANE verbs (`chain show`, `trust-anchor *`).
  Same bare-string format the joined compose smoke writes into sidecar
  key dirs — this file never grows structure.
* `{tenant_id}.session` — JSON, mode 0600, written by `aac sso login`:
  the short-lived AAC session token + its client-computed expiry. The
  ADMIN-surface verbs ride it automatically. A session within 30s of
  expiry fails fast locally with the re-login message instead of
  dialing out; the server's own session 401s carry the same
  remediation (the server stays authoritative). `aac sso logout`
  removes the file; `aac sso whoami` reports its tenant + expiry
  (B155 — both operate on the cache file only).

## Your tenant_id

`tenant_id` is your org's FEDERATION IDENTIFIER — the stable handle
every other tenant verifies your signatures under: it appears in
`X-AAC-Originator-Tenant-Id` headers, `/.well-known/aac-root-keys/
{tenant_id}` paths, SIEM stream directories, and supplier whitelists.
You do NOT choose it (B154 PR 5, Tenant Identifier Policy): the
control plane allocates the canonical **`tnt-<lowercase UUIDv4>`**
(exactly 40 characters, e.g.
`tnt-550e8400-e29b-41d4-a716-446655440000`) at registration, the CLI
captures it into the selected profile, and it is immutable, public,
and never reused — like an AWS account ID. `--parent-tenant-id` takes
the parent org's canonical `tnt-` id — the server resolves handles to
internal row ids; no database identifier ever crosses the API (B118
D3/D4). B121 domain ownership verification is a separate, additive
control tracked in `tenant_domains`: `_aac-challenge.<domain>.` TXT
`aac-verify=<token>`, issued/verified through the tenant-admin commands
above. A verified business domain is evidence only. B182's separate
`bind-trust-domain` request admits a domain's first SPIFFE binding only from
B228-current evidence for the exact same name; parent-domain proof does not
cover subdomains. SPIFFE-valid values outside the DNS proof grammar remain
ceremony-only, and existing binding history remains B181.

## Semantics worth knowing

* `aac chain show` accepts ANY hop's token id or the chain root id
  (`--root-token-id` is an accepted alias); visibility is
  participant-tenant over the symmetric composite closure (Week 12) —
  non-participants get the same 404 as unknown tokens.
* Timelines are §V.2.1 METADATA-TIER: predicates and business
  narratives stay in your tenant SIEM stream; the table output's
  footer says so (§6.1 federated join is the full-fidelity story).
* Exit codes (CLI Config+Profile Spec §14, ratified 2026-08-04 —
  supersedes the originator-cli-era convention): 0 success / 1 remote
  outcome (server rejected/denied, or the server-side resource doesn't
  exist) / 2 invalid command-line usage / 3 invalid local
  configuration or state (missing profile/credential, malformed INI,
  bad registration state) / 4 transport failure (unreachable or timed
  out — the retryable class).
* B159 rate limiting: a numeric server `Retry-After` is rendered beside
  the stable 429/503 error. The CLI never automatically replays a
  mutation; wait for the displayed interval and rerun deliberately.

## Tests

`uv run pytest cli/aac/tests/` — pytest-httpx mocks; no control plane
needed. Against a live stack: bring up the joined topology
(`./bin/run-wedge-a-control-plane-compose.sh --keep-up`) and point the
flags at localhost.
