aac-cli — the aac command

aac is the command-line tool for tenants of Agent Authority Cloud (AAC). AAC lets an organisation's AI agents and services prove, on every request, which tenant they belong to and what they were authorised to do. A tenant is one organisation registered with AAC. Each of its workloads runs beside an AAC sidecar that signs outgoing requests and verifies incoming ones against public trust material the tenant publishes.

New to AAC? What AAC is for explains what delegated authority between agents buys you, and what it does not.

The aac command is how a tenant's operator does everything that is not done by the sidecar itself: register the tenant, sign in, manage keys, workloads and domains, and prepare a runnable local workload. Everything works from a terminal or a script; there is no web console to click through. Output is JSON by default, and every command that reports a result also offers --output table.

Two kinds of tenant use the same tool:

• Developer tenants register themselves by signing in with GitHub or Google. aac init takes a developer from an installed CLI to a runnable local workload in one command.
• Enterprise tenants are registered through an onboarding ceremony with AAC operations and sign in through their own identity provider. Their keys, domains and workloads are managed with the aac tenant and aac sso commands described further down.

Install

pip install aac-cli
aac --version

Python 3.10 or newer is required.

Mind the name. pip install aac installs an unrelated project that happens to share the acronym. The AAC package is aac-cli; the command it installs is aac.

Guided setup for developer tenants: aac init

aac init prepares the AAC side of one of your agents on this machine: it registers the agent's identity with AAC and creates the keys, certificates and configuration its sidecar needs. The agent itself is yours. The first run also creates your profile and registers your tenant; run it again with a new --agent and its own --agent-config file, and the same --trust-url and --idp, for each further agent.

Along the way it signs you in, registers a developer tenant (or reuses the one your profile is already bound to), takes the trust domain AAC assigns to the tenant, registers your workload, generates development keys and certificates, and writes a complete sidecar configuration together with the files the trust-anchor publisher and Docker Compose need.

Point it at the endpoints your AAC environment gives you. The example below uses the AAC stage environment. First save the YAML example in “Agent configuration” below as orders.yaml:

aac init --profile stage --agent orders --agent-config orders.yaml \
  --admin-url https://api.stage.cascadeauth.dev \
  --data-plane-url https://api.stage.cascadeauth.dev \
  --trust-url https://trust.stage.cascadeauth.dev \
  --display-name 'Example Team' --contact 'dev@example.com' --idp github

The command shows what it will create and asks before registering the tenant, because a tenant is permanent. In a script, where there is no terminal to answer the question, pass --create-tenant:

aac init --profile stage --agent orders --agent-config orders.yaml \
  --admin-url https://api.stage.cascadeauth.dev \
  --data-plane-url https://api.stage.cascadeauth.dev \
  --trust-url https://trust.stage.cascadeauth.dev \
  --display-name 'Example Team' --contact 'dev@example.com' --idp github \
  --create-tenant

--idp names how you sign in: github or google, the two sign-ins AAC offers developer tenants. If you need another sign-in provider, contact support@cascadeauth.com.

--trust-url is required when an agent is created: it is the public URL where your AAC environment serves trust material, and for AAC stage it is https://trust.stage.cascadeauth.dev. If you leave it out, the command stops before creating anything and names the value your tenant already uses, if it has one.

Setting up a new developer tenant takes two browser sign-ins: the first registers the tenant, the second starts the tenant-admin session that registers the workload. The command says so before the first one.

Progress lines [1/5] to [5/5] name the five steps: tenant, sign-in, hosted trust domain, workload, and material; the settings files are written last. Rerunning the command is safe: it resumes an interrupted setup, reports a complete agent, or names the exact conflict. It never overwrites private material. The sign-in you chose with --idp is remembered, so a rerun never asks you to pick between GitHub and Google again.

What it creates, and where

• ~/.aac/agents/<agent>/ holds the files one sidecar needs, in folders named for where each file goes. sidecar/ is what you mount or copy into the sidecar: the workload, receipt and HTTPS key pairs, this agent's root-signing key, the CA certificate and the outbound CA bundle. agent/ is what the paired application reads: the pairing secret and the CA certificate. keep/ stays with you — it holds the development CA private key, out of both mounts, so no container ever sees the key that mints identities; an agent whose certificates your own issuer signed has no keep/ at all. Beside them sit sidecar-config.yaml, compose.env, state/ and record.json, which lets a rerun resume.
• ~/.aac/tenants/<tenant-id>/ is tenant-level material shared by every agent of that tenant: the tenant-admin signing key, the publisher's input directories (root-keys/ and spiffe-bundle/, public halves only) and the generated publisher.env.
• ~/.aac/credentials/<tenant-id> is the tenant API key. The generated configuration references it by path.

By default everything aac init generates is development material. The development CA lives seven days and the leaf certificates one day. Nothing there qualifies for production, whatever the tenant's domain. If your own issuer signs your agent's certificates instead, see "Two ways to get your agent's certificates" below; moving to production also means a tenant-admin key under production custody (aac tenant rotate-admin-key) and a root key id published by your publisher.

What an agent folder is for, and how to use it

An agent folder holds everything one workload needs to run beside an AAC sidecar, kept apart from every other workload: its identity in your tenant's trust domain, its own root signing key and key id, its certificates, the pairing secret its sidecar and application share, and the settings files written for them. It also records how far setup got, so rerunning aac init resumes where it stopped.

Use one agent per workload. aac init --agent <name> creates an agent (with --agent-config and --trust-url) or resumes it. There is no default agent; three commands look after it:

aac agent status --agent orders   # what exists, what is due, and the next step
aac agent renew --agent orders    # replace the short-lived certificates
aac agent list                     # every agent on this machine

agent list reports an unreadable or unsupported record in that agent's state and continues listing the others. agent status --agent <name> still returns a local-state error for that individual agent.

There is no separate command for the settings files. Running setup again — with the profile the agent belongs to — writes sidecar-config.yaml, compose.env and the tenant's publisher.env from what the agent already records, without touching a single key:

aac init --profile stage --agent orders                     # write them again
aac init --profile stage --agent orders --layout container  # and change the layout

That is how you rebuild a settings file you lost and how you move between running the sidecar directly on this machine and running it in a container. --profile is required because setup picks the profile before it reads the agent; aac agent status prints the same command with the right profile whenever it is the next step.

A second workload is a second agent with its own workload path:

aac init --profile stage --agent worker --agent-config worker.yaml \
  --idp github --trust-url https://trust.stage.cascadeauth.dev

Pass the same --trust-url and --idp as for your first agent. Each agent records its own, and the trust URL also goes into the tenant's publisher.env, which every agent of the tenant shares. Writing the settings files never changes that file's endpoints, so an agent created with a different trust URL stops at its last step and has to be set up again under a new name.

--agent names the local files and must match the file's agent_name. The file's required workload_path supplies the path at the end of the SPIFFE ID. An optional --workload-path must match the file or saved identity; omission on refresh reuses that identity. Missing or conflicting identities are refused. Two agents with the same workload path are the same workload holding different keys: that is what a replacement computer wants, and what a second workload does not. The agent name is permanent, because the root key id is made from it. aac init needs the profile the agent was created with; the aac agent commands read it from the agent itself.

Agent configuration

The operator writes one YAML file. aac init --agent-config PATH validates and explicitly applies it. The profile remains INI; this file describes one agent, not its profile or the hosted service. For example, save this as orders.yaml:

agent_name: orders
workload_path: fulfilment/orders
tls_server_names: [orders.internal.example, localhost, 127.0.0.1]
sidecar:
  agent_invoke_url: http://127.0.0.1:8000/invoke
  external_bind_address: 127.0.0.1
  telemetry:
    sink: orders.jsonl
    central_forward: false
classes_of_action:
  fulfil_order:
    predicates:
      action: reserve_inventory
      amount_max: 10000
      originator_reference: "PO #4143"
    valid_for: +8m
destinations: {}

This declares the tenant's permission; AAC does not invent one. The application chooses fulfil_order when starting a chain and checks that its business action matches the authorized context. Units and business meaning belong to the application. Empty classes and destinations are allowed for registration before peer identities are known. No self destination is added.

Chain-start boundary: restrict /v1/agent/delegations and /v1/agent/mint-root to the authorized originating application at the network/ingress boundary. Sidecar v0.4.0 and later also require the existing pair's AAC1-HMAC-SHA256 signature over the exact alias and raw request body. Older releases do not authenticate these callers, so sharing a private network with peers is insufficient. An authorized separate originator may hold the pair secret only inside the same trusted tenant-application boundary; it gains callback-signing capability too. Never share secrets across pairs or tenants. Pairing freshness is not idempotent chain creation; do not automatically retry an uncertain mint. Development certificates do not require dev_mode.

Applications using v0.4.0 can supply per-request obligations for T1. Equal configured/request values combine once; differing values refuse rather than override or intersect. Put dynamic limits in the request instead of also configuring a different class value. Native request valid_until is reserved; remove it and use class valid_for. For signed correlation, normally supply a task_ref obligation per request: top-level task_ref alone is correlation metadata, while a static class predicate deliberately shares one convergence key across that class's chains. Omitted/null metadata inherits a configured or obligation predicate; an explicit conflicting value refuses before minting.

The following is the complete input schema. Unknown fields, duplicate mapping keys, YAML aliases/merge keys, object tags and files over 64 KiB are refused. Null is not an omitted value. Strings must be nonempty and have no surrounding whitespace or control characters. Lists allow at most 128 unique values; class and destination maps allow at most 128 entries each.

Field	Type and meaning	Default when omitted
agent_name	Required local name, 3–15 characters under the same name rules as --agent; must match it.	None
workload_path	Required concrete SPIFFE path, 3–150 ASCII characters; slash-separated letters/digits/._~-, no empty or dot segments, wildcard, query or escaped character. Fixed once the agent exists.	None
tls_server_names	Required nonempty list of DNS names/IP addresses callers use for HTTPS, including the originating application. No URLs, wildcards or unspecified bind addresses.	None
sidecar.dev_mode	Boolean enabling the runtime's development exceptions; independent of certificate source and replay profile.	false
sidecar.loopback_bind_address	Must be exactly 127.0.0.1 when dev_mode: false; another loopback IP address requires dev_mode: true. Non-loopback addresses are not accepted by this input.	127.0.0.1
sidecar.external_bind_address	IP bind address for the peer listener; choose the reachability your ingress allows.	127.0.0.1
sidecar.loopback_port, sidecar.external_port	Distinct integer ports, 1–65535.	8080, 9443
sidecar.agent_invoke_url	Absolute HTTP(S) URL of your application's invoke endpoint.	http://127.0.0.1:8000/invoke
sidecar.log_level	debug, info, warn or error.	info
sidecar.telemetry.sink	Filename within managed state/ (letters/digits/_.-, starting with a letter/digit), or stdout / none. a2a-egress.db is reserved for managed database state, regardless of case or whether A2A is enabled. Host/container paths are generated.	telemetry.jsonl
sidecar.telemetry.central_forward	Boolean opt-in for asynchronous metadata-only forwarding. The endpoint and tenant API-key file come from the selected profile/agent binding, never another tenant's file.	false
replay_protection.backend	memory or valkey.	memory
replay_protection.deployment_profile	basic with memory; ha-retained-write-safe with Valkey. No fallback.	The matching profile
replay_protection.url	Required absolute valkeys:// URL for Valkey, with an optional numeric database path. No query, fragment or embedded credentials. Not valid with memory.	None
replay_protection.memory_max_entries	Integer 1–1000000.	100000
replay_protection.connect_timeout_ms	Integer 1–100.	Runtime default 100
replay_protection.operation_timeout_ms	Integer 1–250.	Runtime default 50
replay_protection.max_connections	Integer 1–4096.	Runtime default 32
replay_protection.cold_start_quarantine_seconds	Integer 120–3600.	Runtime default 120
trust_anchors.tenant_ids	Additional canonical tnt-<UUID> tenant IDs whose root signatures you trust.	Empty; own tenant is always included
spiffe_bundles.trust_domains	Additional lowercase trust domains whose workload certificates you trust.	Empty; own assigned domain is always included
https_trust.ca_files	Paths to public PEM CA certificate files, relative to the input file or absolute; up to 256 KiB each and 1 MiB total. Certificate-only PEM is saved; refresh/renewal do not reread the source files. No private keys.	Empty; own CA is always included
https_trust.system_roots	Boolean adding the current machine's system public HTTPS roots, with certifi fallback. With false, every outbound TLS service—including the control plane, trust URL, peer and Valkey—must chain to the own CA or a CA listed in ca_files.	true
classes_of_action.<name>.predicates	Mapping of registered predicate names to supported values, described below. The class entry's <name> uses letters/digits/_.-, starting with a letter/digit, up to 128 characters; predicate names come only from the closed registry.	Empty mapping
classes_of_action.<name>.valid_for	Required positive duration, 1 second–24 hours: digits with optional +, then s, m, h or d. The CLI supplies the registered audience_self.	None
destinations.<name>.url	Required absolute HTTPS recipient URL, for native receive or A2A.	None
destinations.<name>.audience_pattern	Required exact registered SPIFFE identity; no wildcard.	None
destinations.<name>.predicates, .valid_for	Same value/duration contract as classes.	Empty predicates; duration required
destinations.<name>.timeout_ms	Integer 1–2147483647 without A2A; 1–60000 for every destination when A2A is enabled, matching its generated deadline.	10000
a2a.public_base_url, a2a.local_handler_url	Optional A2A block; both required if present. Public URL is HTTPS with no path except optional /; the HTTP(S) local handler path must be exactly /a2a/v1, with no escaped spelling. Neither URL permits query or fragment markers, even empty ones. Managed A2A state paths and a 60-second deadline are generated. No A2A self-route is added.	A2A disabled

URL hosts are ASCII DNS names or IP addresses; URL fields reject whitespace, backslashes, embedded credentials and fragments. Basic replay history is process-local: restarting loses it, and replicas do not share it. Selecting Shared durable declares that the operator has qualified the Valkey service; the CLI does not establish durability. This configuration interface does not accept credential-bearing replay URLs.

The three kinds of trust above are separate checks. Obtain peer tenant IDs, assigned trust domains and exact workload identities from their public status or registration output. Exchange public CA certificates only. After registering both agents, explicitly apply their peer configurations with the same command:

aac init --profile stage --agent orders --agent-config orders.yaml

The closed predicate registry accepts action, amount_max, amount_min, amount, valid_from, beneficiary_account, beneficiary_class, currency, data_scope, purpose, human_authorization_class, task_ref, min_account_age_days, max_authority_amount, assessed_damage_amount, assessment_outcome, surveyor_findings, payout_amount, program_reference, reporting_quarter, claim_ref, hours, quantity_units, beneficiary, unit_price_usd, account, esg_scope3_co2e_kg, conflict_minerals_clear, originator_reference, scope, composite_payout_amount, composite_payout_total, composite_units_total, composite_esg_scope3_co2e_kg_total and composite_conflict_minerals_clear. amount_max, amount_min and valid_from accept nonnegative integers or canonical decimal strings (0 or a nonzero digit followed by digits), at most 9223372036854775807. Enforced numbers are checked before YAML integer conversion: spellings such as 010, 0x10, 1_000 and +10 are refused, quoted or unquoted, so the loader cannot silently reinterpret a limit. Other values must be strings. Commas are refused because they separate wire predicates. The combined mapping has a 7900-byte UTF-8 budget, leaving room for the generated expiry.

valid_until is generated authority data, so it is refused in static input: use valid_for. Registry membership alone does not give business labels new monotonic enforcement. The current HTTP mint route uses the selected class's static first limits; it accepts no per-request obligations. Your application remains responsible for its policy decision.

Applying a file rewrites the generated configuration; restart the sidecar to load it. Ordinary refresh and certificate renewal use the saved accepted values, even if the original file is edited, moved or removed. Public CA file changes also require explicit reapplication. The source file is never rewritten. Keep the agent directory, credentials and keys; the input file is not their backup. Generated files are disposable outputs and should not be hand-edited.

HTTPS certificates must authenticate every configured connection name. The CLI issues them for those names or checks supplied certificates against them; renewal keeps those names. Applying a different name set requires the installed certificate to cover it already: supplied issuers can issue a certificate covering both sets before the change. A CLI-issued agent needing new names must be created under a new name with the intended configuration. No old agent-record format is migrated.

Central forwarding retains the local sink and sends only permitted metadata. It is asynchronous and best-effort; a local event does not prove central delivery. It excludes business predicates, task references, raw tokens/proofs and receipts. AAC_TELEMETRY_SINK and AAC_AGENT_STATE_DIR in compose.env identify the local file and mount; AAC_API_KEY_FILE identifies this tenant's credential. Mount it at /run/secrets/tenant-api-key in the container layout. Do not read private record.json from consumers.

For a CA change: stop the affected sidecar/application; renew or install the issuer's replacement certificates; restart the publisher and verify publication with aac agent status --agent <name> --remote; exchange the new public CA with each intended peer and explicitly reapply that peer's configuration; then restart the sidecars/applications and verify traffic in both directions. A peer's files are never changed implicitly. Old published CA anchors remain until deliberately retired. Leaf-only renewal needs a sidecar restart, without changing peer trust.

Two ways to get your agent's certificates

Find your situation here and use the flags it lists. Nothing is inferred: which case you are in is decided by whether you pass certificates your own issuer signed, and the agent records the answer, so aac agent status can tell you later and aac agent renew behaves accordingly.

The CLI creates a development CA

The laptop case. The CLI creates a certificate authority on this machine and signs the agent's identity, receipt and HTTPS certificates with it.

Flags. No flags are needed. To reuse a development CA across agents, pass --ca-key-file and --ca-cert-file together; neither one alone.

Keys and signatures. The CA and the two identity keys are Ed25519; the HTTPS key is EC P-256.

The CLI creates a 7-day certificate authority and keeps its private key in the agent's keep/ folder; issues the workload, receipt and HTTPS certificates; publishes the CA certificate as a trust anchor named <agent>-dev-ca.

The CLI does not ask you for anything from your own certificate authority.

Renewal. aac agent renew --agent <name> issues fresh certificates from the same CA.

I bring my own CA

Your own issuer has signed the agent's certificates, and your CA private key never reaches this machine. Certificate source alone does not qualify a production deployment.

Flags. All seven together: --workload-cert-file, --terminal-cert-file and --tls-cert-file, each with its key file (--workload-key-file, --terminal-key-file, --tls-key-file), plus --ca-cert-file. Never --ca-key-file: the CLI does not want your CA key.

Keys and signatures. Your CA's key must be Ed25519 or EC P-256, and it must have signed each certificate with Ed25519 or ECDSA-with-SHA-256. The two identity keys may be Ed25519 or EC P-256; the HTTPS key must be EC P-256. RSA is not supported: the sidecar cannot verify against it.

The CLI checks each certificate against its key, its issuer and its validity window, and HTTPS certificates against every configured connection name; registers the workload and writes the settings files and the pairing secret; publishes your CA certificate as a trust anchor named <agent>-ca.

The CLI does not create a certificate authority; issue any certificate; ask for, read or store your CA private key.

Renewal. aac agent renew --agent <name> cannot reissue what it did not sign: it takes the replacements your issuer produced.

The settings files, sidecar-config.yaml and compose.env in the agent folder and publisher.env in the tenant directory, follow from what the agent records, in both cases. They hold endpoints, identifiers, settings and the paths of the key files, never key material. aac init writes them as its last step and writes them again on any later run. The layout decides the paths written into the sidecar configuration: host (the default) uses paths on this machine, for a sidecar that runs directly on it, and container uses the paths where the files are mounted inside the containers.

publisher.env belongs to the tenant, and every agent of the tenant writes it. A write rewrites its paths and poll interval for this machine (hand edits to those are replaced), but refuses to change its tenant ID, trust domain or URLs, because that would repoint the publisher for every agent. The refusal names the values that differ. If the file is the stale one, for example after you deliberately moved the tenant to new endpoints and set up its agents again, move it aside (mv publisher.env publisher.env.old in the tenant directory) and run setup again from an agent with the intended endpoints. The admin key and the published public keys stay where they are.

How profiles, agents and tenant data fit together

profile (~/.aac/config) ── bound to ──> tenant
                                          ├── credentials:      ~/.aac/credentials/<tenant-id>
                                          ├── tenant directory: ~/.aac/tenants/<tenant-id>/
                                          └── agents:          ~/.aac/agents/<name>/, one per workload

• A profile, in ~/.aac/config, names the AAC admin and data-plane endpoints you use and, once registration or sign-in has bound it, the one tenant it acts for. The trust URL and the sign-in choice are recorded in each agent instead. "Profiles and configuration", further down, covers profiles in full.
• The tenant data is shared by all of a tenant's agents on this machine: the tenant API key and the tenant-admin session in ~/.aac/credentials/, and the tenant directory ~/.aac/tenants/<tenant-id>/ with the tenant-admin signing key, the public keys and certificates the publisher uploads, and publisher.env.
• An agent folder, in ~/.aac/agents/<name>/, holds one workload's material. It records the profile and the tenant it was created for and keeps them: one tenant can have many agents, and an agent never moves to another tenant.

What each file is for, and what to back up

The table lists every file the CLI creates, what it is for, how long it lives and whether to back it up. <agent> is your explicitly selected agent name and <tenant-id> the tenant id AAC allocated.

For what each of these proves, who else ever gets a copy, what never leaves you and how the pieces fit together — including when your own certificate authority signs instead of this tool — see Keys and certificates.

No.	Material	Where	Used for	Lifetime	Back up?
1	tenant_api_key	~/.aac/credentials/<tenant-id>	CLI data-plane calls; the sidecar's workload projection	until retired or rotated; aac tenant reissue-api-key	Yes. save a protected copy in your secret manager; loss needs aac tenant reissue-api-key
2	tenant_admin_session	~/.aac/credentials/<tenant-id>.session	CLI admin calls	hours; aac sso login	No. sign in again
3	tenant_admin_signing_key	~/.aac/tenants/<tenant-id>/tenant-admin.pem, ~/.aac/tenants/<tenant-id>/tenant-admin.pub.pem	the publisher signs trust-material uploads; the public half is registered with AAC	until rotated; aac tenant rotate-admin-key	Recommended. recommended for developer tenants (loss needs aac tenant rotate-admin-key; a lost public half is derived from the private key); production custody belongs in an HSM/KMS, not a password manager
4	root_signing_key	~/.aac/agents/<agent>/sidecar/root.pem, ~/.aac/agents/<agent>/sidecar/root.pub.pem, ~/.aac/tenants/<tenant-id>/root-keys/<agent>-root-v1.pub.pem	the sidecar mints authority chains; the public half is published under the key id	until you retire its key id (root key ids are fixed per agent name)	No. never restore the private key: a replacement agent gets a new name and therefore a new key id, published alongside the old one until the old one is retired; its public copies are recreated from it
5	development_ca	~/.aac/agents/<agent>/keep/ca.key, ~/.aac/agents/<agent>/sidecar/ca.crt, ~/.aac/agents/<agent>/agent/ca.crt, ~/.aac/tenants/<tenant-id>/spiffe-bundle/<agent>-dev-ca.ca.pem	signs the workload, terminal and TLS certificates; peers trust it via the published bundle	7 days; aac agent renew --ca	No. development only; reissue; a lost copy of the certificate is copied back from sidecar/ca.crt
6	workload_svid	~/.aac/agents/<agent>/sidecar/workload.key, ~/.aac/agents/<agent>/sidecar/workload.crt	the sidecar's SPIFFE identity: proves on every live request that this workload holds the key behind its certificate	1 day; aac agent renew	No. reissue
7	terminal_attestation	~/.aac/agents/<agent>/sidecar/terminal.key, ~/.aac/agents/<agent>/sidecar/terminal.crt	signs the receipt (terminal attestation) the sidecar issues when this workload completes a delegated request; auditors verify it offline against your published CA; setup gives it its own key so the two signing jobs stay separate, but a receipt is verified against your published CA and the expected agent identity, which the workload certificate also satisfies — treat both keys as one blast radius	1 day; aac agent renew	No. reissue
8	https_tls	~/.aac/agents/<agent>/sidecar/server.key, ~/.aac/agents/<agent>/sidecar/server.crt	the sidecar's HTTPS listener	1 day; aac agent renew	No. reissue
9	outbound_ca_bundle	~/.aac/agents/<agent>/sidecar/outbound-ca.pem	the sidecar verifies TLS to AAC and configured peers	rebuilt by renew; aac agent renew	No. derived
10	pairing_secret	~/.aac/agents/<agent>/agent/pairing.secret	the sidecar and its agent authenticate each other (same bytes in both)	until regenerated	No. regenerable; both processes must read the same file
11	agent_record	~/.aac/agents/<agent>/record.json	the agent's identities and progress; every aac agent verb reads it first	for the life of the agent	Recommended. cannot be recreated by any command; without it start a new agent under a new name (see the new-computer setup procedure)
12	published_public_inputs	~/.aac/tenants/<tenant-id>/root-keys, ~/.aac/tenants/<tenant-id>/spiffe-bundle	the publisher's input directories: every root public key and CA certificate this tenant has published, across all agents	for the life of the tenant	Recommended. back up with the tenant directory: a replacement agent must publish its new root key alongside a still-ACTIVE previous one (the control plane refuses a root-key set that drops every ACTIVE key at once)
13	settings_files	~/.aac/agents/<agent>/sidecar-config.yaml, ~/.aac/agents/<agent>/compose.env, ~/.aac/tenants/<tenant-id>/publisher.env	non-secret settings derived from the agent's record	written again on demand; aac init --profile <profile> --agent <agent>	No. derived; aac init --profile <profile> --agent <agent> writes them again

In short: back up the tenant API key and the whole tenant directory while the machine is healthy. Everything else is regenerated.

Inspect and maintain an agent

aac agent status --agent orders --output table   # what exists, expiry, permissions, next command
aac agent status --agent orders --remote         # also: is the public trust material visible?
aac agent renew --agent orders                   # replace the short-lived certificates; old ones archived
aac agent list                                    # every agent on this machine, with its case
aac init --profile stage --agent orders --layout container   # write the settings again, container paths

status works offline by default and exits with code 3 when material is missing, expired or unsafely permissioned. renew reissues the one-day certificates with fresh keys, and reissues the development CA only when it is expired or within a day of expiry (or when --ca is given); a new CA is published under the next anchor id and needs the publisher restarted. For an agent whose own issuer signed its certificates, renew cannot reissue anything: it takes the replacements your issuer produced, through the same flags aac init accepts. Re-running aac init writes the settings files again and never touches a key.

status also names one next step, next_command. When material is missing, it is the fix for the first missing item: restore it from your backup, recreate a lost public copy from the file it copies, renew, or run setup again. Otherwise it is renewal when a certificate is due. After the step, run status again. Commands it names that change your tenant carry the agent's own --tenant-id and --admin-url, so a value left in AAC_TENANT_ID or AAC_ADMIN_URL cannot aim them at another tenant. The file recipes use openssl, which must be OpenSSL 1.1.1 or newer: the openssl that ships with macOS cannot read Ed25519 keys, so install a current OpenSSL there, for example with Homebrew.

Every private file is created once, readable only by you, and never overwritten. Before generating anything, init checks every destination and refuses with the full list if one already exists. aac init never installs or replaces a tenant-admin key for an existing tenant: the key on this machine must already be the tenant's active admin key, and replacing it is always the deliberate aac tenant rotate-admin-key command, never a side effect of setup. A second agent for the same tenant (--agent other) reuses the tenant-admin key and gets its own root key id.

What to do when keys and certificates expire

It is the certificates that expire, and renewing replaces their keys with them. aac agent status shows when each certificate runs out and flags it before it does: six hours ahead for the one-day certificates, a day ahead for the development CA.

Material	Lasts	When it runs out	What to do
Workload, terminal-attestation and HTTPS certificates	1 day	the sidecar can no longer prove its identity, sign receipts or serve HTTPS	aac agent renew --agent <name>, then restart the sidecar so it loads them
Development CA	7 days	certificates it signed stop being trusted, and no new ones can be issued	renew also replaces the CA when it is expired or within a day of expiry, or when --ca is given, and then reissues every certificate under it: restart the publisher so the new CA is published, restart the sidecar and anything else that trusted the old CA, and confirm with aac agent status --agent <name> --remote
Tenant-admin session	hours	administration commands ask you to sign in again	aac sso login
Tenant API key, tenant-admin signing key, root signing key	do not expire	—	replaced only on purpose: see "Keys" and "Setting up aac-cli on a new computer"

A simple routine: when you start work, run aac agent status --agent <name>, and when it names renewal, run aac agent renew --agent <name> and restart the sidecar. About once a week that renewal also replaces the development CA (renew then reports republication_required: true): restart the publisher, the sidecar and the agent, and anything else that trusted the old CA. Renewing is safe to repeat, but it is not a no-op: every run issues fresh keys and moves the old files to the agent's archive/ directory, so whatever reads them must reload. Recreate or restart the affected processes with your deployment's normal commands after publishing and explicitly refreshing each peer's public trust. Restarting a process does not renew its certificates.

All of this is development material. In production, certificates come from your own issuer and follow its renewal process.

Setting up aac-cli on a new computer

This procedure covers a lost machine and a second machine alike. It needs the two backups named above: the tenant API key from ~/.aac/credentials/<tenant-id> and the tenant directory ~/.aac/tenants/<tenant-id>/. The tenant id is the tnt-… value in your profile; aac profile show prints it, and the example below uses tnt-550e8400-e29b-41d4-9716-446655440000.

1. Install the CLI, create the profile, and sign in. Signing in needs the tenant id, because a fresh profile is not yet bound to a tenant:

   pip install aac-cli
   aac profile create stage \
     --admin-url https://api.stage.cascadeauth.dev \
     --data-plane-url https://api.stage.cascadeauth.dev
   aac sso login --profile stage --idp github \
     --tenant-id tnt-550e8400-e29b-41d4-9716-446655440000
   

   An enterprise tenant signs in through its own identity provider instead, naming the connection by its URL:

   aac sso login --profile stage \
     --idp-url https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/v2.0 \
     --tenant-id tnt-550e8400-e29b-41d4-9716-446655440000
   

2. Restore the tenant API key to ~/.aac/credentials/<tenant-id>, readable only by you, or issue a new one if it was not backed up:

   aac tenant reissue-api-key --profile stage
   

   Restore ~/.aac/tenants/<tenant-id>/ from the backup, with directories readable only by you and files likewise. Its publisher.env still names the old machine's paths; step 3 rewrites them for this one.

   If the tenant directory was not backed up, first check whether another machine still holds ~/.aac/tenants/<tenant-id>/: every machine that has run aac init for this tenant has one. If so, copy it from there. That is the backup, and the rest of this step does not apply.

   If no copy exists anywhere, the tenant-admin key and every root key that lived on the lost machine are gone for good. Install a new admin key, then account for every root key the tenant has published (the openssl commands need OpenSSL 1.1.1 or newer, which macOS does not ship):

   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 --profile stage \
     --tenant-admin-pubkey-file tenant-admin.public.pem
   aac trust-anchor list --profile stage --role root-signing --output table
   aac trust-anchor revoke --profile stage --kid starter-root-v1 \
     --reason 'machine lost'
   

   The list shows each root key with its state. A publisher may drop a key from its published set only while another active key stays in the set, so a set holding nothing but the new key is accepted only once no other key is active. Revoke every active key whose private half was lost, one revoke per key id, and no other key: a root key that is still in use elsewhere must stay active, and its public file must be in the tenant directory the publisher runs from. Then run step 3 with --tenant-admin-key-file tenant-admin.pem added.

3. Prepare laptop-2.yaml with the new agent_name and the original workload path, deployment and trust choices. Run setup with that new agent name. A developer tenant passes its sign-in choice, so an expired session is renewed without a prompt:

   aac init --profile stage --agent laptop-2 --agent-config laptop-2.yaml --idp github \
     --trust-url https://trust.stage.cascadeauth.dev
   

   An enterprise tenant runs the same command without --idp; --idp selects only the GitHub and Google developer sign-ins. The guided setup then uses the session from step 1. If that session has expired, repeat the aac sso login --idp-url … command from step 1 first:

   aac init --profile stage --agent laptop-2 --agent-config laptop-2.yaml \
     --trust-url https://trust.stage.cascadeauth.dev
   

4. Start the publisher from the tenant directory, restored or written by step 3. A restored directory's root-key set holds the old and the new public keys, which is exactly what AAC requires: a set that drops every currently active key at once is refused. Retire the old key later, by removing its public file, once nothing signs with it. A directory written fresh after the revocations in step 2 holds only the new key, which is accepted because no other key is active any more.

Why the replacement agent needs a new name

The agent name is baked into two identifiers that are published for the whole tenant: the root key id <agent>-root-v1 and the CA anchor id (<agent>-dev-ca for a development CA the CLI created, <agent>-ca for your own issuer's). Other parties look up your keys and certificates by those ids. AAC therefore never accepts new key material under an id that has already been published: a key id names one key, for good. A new machine has to generate new keys, so it has to publish them under new ids, which means a new agent name. The new ids are published alongside the old ones until the old ones are retired.

Reusing the old agent name on the new machine is refused on purpose: the restored tenant directory still holds that name's published root key, and init never generates different key material under an existing key id. The development certificates and the pairing secret are regenerated by step 3; they are never restored.

Profiles and configuration

A profile is a named set of endpoints plus the tenant the profile is bound to. Profiles live in ~/.aac/config, a plain INI file with one section per profile:

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

[stage]
admin_url = https://api.stage.cascadeauth.dev
data_plane_url = https://api.stage.cascadeauth.dev

aac profile list                                  # every profile, including the built-in main
aac profile show stage --output table             # stored and effective values, with sources
aac profile create prod --admin-url https://aac-admin.example.com \
  --data-plane-url https://aac-data.example.com
aac profile update main                           # edit the built-in baseline
aac profile delete prod                           # local only; never touches the server

main is the reserved baseline profile. It always exists, with localhost defaults until aac profile update main stores real values, and cannot be created or deleted. Every operational command selects its profile in this order: --profile <name>, then the AAC_PROFILE environment variable, then main. A selected profile that does not exist is an error, never a silent fallback. Within the selected profile, a flag beats an environment variable (AAC_ADMIN_URL, AAC_DATA_PLANE_URL, AAC_TENANT_ID), which beats the stored value.

tenant_id is managed for you. Profile commands display it but never ask for it; only aac tenant register, aac init and aac sso login write it. It is your organisation's identifier in the federation, allocated by AAC at registration in the form tnt-<uuid>, and it never changes.

AAC_CLI_HOME relocates the whole ~/.aac tree. Use it for a throwaway test home, or to keep separate accounts hard-walled from each other:

AAC_CLI_HOME=$HOME/.aac-prod aac profile list

Credentials

Two credential files can coexist under ~/.aac/credentials/:

• <tenant-id> holds the tenant API key, written once by registration and printed exactly once. The sidecar and the data-plane commands (aac chain, aac trust-anchor) present it. Only a hash of it exists on the server, so a lost key is replaced, never recovered.
• <tenant-id>.session holds the short-lived session that aac sso login creates. The administration commands (aac tenant, aac sso) use it automatically. Sessions cannot be refreshed: when one expires, any administration command tells you to sign in again, and there is no refresh token that could be stolen.

Signing in

aac sso login --profile stage --idp github                # developer tenant: GitHub or Google
aac sso login --profile prod \
  --idp-url https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/v2.0
aac sso login --profile prod \
  --idp-url https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/v2.0 \
  --flow pkce --no-browser                                # print the URL instead of opening a browser
aac sso whoami --profile stage --output table            # cached session and the tenant's assigned domain
aac sso logout --profile stage

A developer tenant signs in with --idp github or --idp google; if you need another sign-in provider, contact support@cascadeauth.com. An enterprise tenant signs in through its Microsoft Entra ID connection, named by the connection's exact URL with --idp-url; when several connections are registered, the error message lists the exact commands to choose one.

Sign-in uses the device flow by default, so the browser can be on another machine and headless hosts work. Google connections use a loopback flow instead, because Google's device flow is scope-restricted; --flow overrides the choice. whoami and logout work offline and never contact AAC.

Output and exit codes

Every command that reports a result prints one JSON document to standard output by default, with progress notes and diagnostics on standard error, so the JSON stays parseable in scripts; --output table prints a readable table instead. The three profile writers are the exception: aac profile create, update and delete confirm on standard error, leave standard output empty and take no --output.

Exit code	Meaning
0	Success.
1	AAC or the identity provider rejected the request.
2	Usage error: an invalid flag, value or flag combination.
3	A local configuration or state problem: profile, credential file, cached session or agent.
4	Transport failure: an endpoint could not be reached.

If AAC asks you to slow down, the command shows the interval to wait. The CLI never replays a change on its own; wait and rerun deliberately.

Enterprise tenants

Enterprise tenants are registered through an onboarding ceremony: AAC operations opens a registration window and hands the tenant operator a bootstrap token, which the commands below read from --bootstrap-token or the AAC_BOOTSTRAP_TOKEN environment variable. The token authorises only the onboarding steps shown with it; every other administration command runs under a signed-in session.

For enterprise sign-in, AAC supports Microsoft Entra ID (also known as Azure Active Directory or Azure AD). If your organisation needs another identity provider, contact support@cascadeauth.com.

Register the tenant

Generate the tenant-admin key pair first. The CLI transmits the public half only and refuses a private key:

openssl genpkey -algorithm ed25519 -out tenant-admin.pem
openssl pkey -in tenant-admin.pem -pubout -out tenant-admin.public.pem
aac profile create prod --admin-url https://aac-admin.example.com \
  --data-plane-url https://aac-data.example.com
aac tenant register --profile prod --display-name 'Example Corporation' \
  --contact ops@example.com \
  --workload-spiffe-id spiffe://example.com/treasury-agent/v1 \
  --tenant-admin-pubkey-file ./tenant-admin.public.pem \
  --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"

AAC allocates the tenant id; you never choose one. The response prints the id and the tenant API key exactly once, and the CLI saves both. A profile that is already bound to a tenant refuses to register another; use an unbound profile. If the response is lost, rerun the same command with no changes to the identifying flags: the CLI resumes the frozen request rather than registering twice.

aac tenant describe --profile prod --output table
aac tenant update --profile prod --tenant-id tnt-550e8400-e29b-41d4-9716-446655440000 \
  --display-name 'Example Corporation Ltd'

Connect your identity provider

An identity-provider connection is described by a JSON file (aac sso register-idp --help shows the fields, with an example for a Microsoft Entra ID tenant). Before the first connection, generate an offline recovery key so the connection can be repaired if the provider is ever unavailable; only the enrollment file leaves the machine:

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 --profile prod \
  --file idp-recovery-enrollment.json --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"
aac sso register-idp --profile prod --file connection.json \
  --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"
aac sso list-idp --profile prod

Later connections, corrections (aac sso replace-idp) and the two-party repair ceremony (aac sso request-idp-repair, aac sso approve-idp-repair) are described by their --help.

Keys

Replacing the tenant-admin key is immediate and forward-only: the previous key stops verifying at once and can never be reinstated. The trust-anchor publisher signs its uploads with this key and loads it once, at start, so sequence the change: stop the publisher, register the new public half, put the new private key where the publisher's configuration points, start the publisher, and confirm that its first upload is accepted under the new key. A publisher installed as a system service reads the key path from its environment file, which you can point at the new file. A Docker publisher's environment and key mount are fixed when the container is created, so overwrite the key at the mounted path and recreate the container; a plain restart would come back on the old key.

aac tenant rotate-admin-key --profile prod \
  --tenant-admin-pubkey-file tenant-admin.public.pem

A developer tenant set up with aac init keeps its tenant-admin key in its tenant directory, where the publisher's configuration points. To replace a lost key there, write the new pair in place, readable only by you, sign in, register the new public half, and then recreate every publisher container. Pass the tenant id and admin URL explicitly, as aac agent status does, so the change cannot land on another tenant. The openssl commands need OpenSSL 1.1.1 or newer, which macOS does not ship:

cd ~/.aac/tenants/tnt-550e8400-e29b-41d4-9716-446655440000
(umask 077 && openssl genpkey -algorithm ed25519 -out tenant-admin.pem.tmp && mv tenant-admin.pem.tmp tenant-admin.pem)
(umask 077 && openssl pkey -in tenant-admin.pem -pubout -out tenant-admin.pub.pem.tmp && mv tenant-admin.pub.pem.tmp tenant-admin.pub.pem)
aac sso login --profile stage --idp github \
  --tenant-id tnt-550e8400-e29b-41d4-9716-446655440000 \
  --admin-url https://api.stage.cascadeauth.dev
aac tenant rotate-admin-key --profile stage \
  --tenant-id tnt-550e8400-e29b-41d4-9716-446655440000 \
  --admin-url https://api.stage.cascadeauth.dev \
  --tenant-admin-pubkey-file tenant-admin.pub.pem

The tenant API key can be rotated without downtime. issue stages a second active key in a new file and never replaces the current one; move every client to it, then retire the old key by its exact id:

aac tenant api-key list --profile prod
aac tenant api-key issue --profile prod
aac tenant api-key retire --profile prod --key-id ak_0123456789abcdef --yes

A lost or suspected-compromised key is replaced instead: every active key is revoked and one fresh key is printed once.

aac tenant reissue-api-key --profile prod

Domains and workloads

Every tenant gets an AAC-assigned trust domain: the tenant id plus a suffix the control plane selects for its environment, <tenant_id>.tenants.stage.cascadeauth.dev on stage and <tenant_id>.tenants.cascadeauth.com on production. No DNS record or proof of ownership is needed; the first call allocates the name permanently and every later call returns the same one, so use the name the command returns rather than building it yourself. Registration saves it in the profile as hosted_trust_domain. Signing in with aac sso login does not write it: aac tenant assign-hosted-domain requests the same allocation and saves it into the profile bound to that tenant, as aac init does during setup. To use a custom domain you own as a trust domain instead, prove control of it with a DNS TXT record, then bind it; a domain you own is recorded on the server and never written to the profile:

aac tenant issue-domain-challenge --profile prod --domain example.com
# Publish the TXT record the command prints, then:
aac tenant verify-domain --profile prod --domain example.com
aac tenant bind-trust-domain --profile prod --trust-domain example.com
aac tenant list-trust-domains --profile prod --output table

Workloads are the identities your sidecars run under:

aac tenant add-workload --profile prod --spiffe-id spiffe://example.com/payroll/v1 \
  --display-name Payroll
aac tenant list-workloads --profile prod
aac tenant deactivate-workload --profile prod --workload-id wl-2f9c1e --reason 'service retired'

Deactivation is terminal, and a deactivated SPIFFE id stays reserved.

Inspect trust material and audit a chain

aac trust-anchor list --profile prod --output table          # every published key, every lifecycle state
aac trust-anchor describe --profile prod --kid starter-root-v1
aac chain show --profile prod \
  --token-id c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9 --output table
aac chain show --profile prod \
  --token-id c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9 \
  --render --render-out ./chain.html

chain show accepts any hop's token id or the chain root id and shows the chain to any tenant that took part in it. The timeline carries metadata only; the business content of each step stays in your own audit stream.

Getting help

aac --help lists the command groups and aac <command> --help shows every flag with its default. Errors name the exact command to run next.

License

Apache-2.0.