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.

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 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 a sample 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:

aac init --profile stage \
  --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 \
  --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

Progress lines [1/5] to [5/5] name the five steps: tenant, sign-in, hosted trust domain, workload, and material; the configuration files are rendered last. Rerunning the command is safe: it resumes an interrupted setup, reports a complete workspace, 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/workspaces/<workspace>/ is the workspace for one workload (default name starter). pki/ holds what the sidecar container mounts: the workload, terminal-attestation and localhost TLS key pairs, this workspace's root-signing key and the outbound CA bundle. pair/ holds what both containers mount as secrets: the pairing secret and the public development CA certificate. ca/ holds the development CA private key, kept out of both mounts so no container ever sees the key that mints identities. Beside them sit sidecar-config.yaml, compose.env and a manifest that lets a rerun resume.
• ~/.aac/tenants/<tenant-id>/ is tenant-level material shared by every workspace of that tenant: the tenant-admin signing key, the publisher's input directories (root-keys/ and spiffe-bundle/, public halves only) and the rendered publisher.env.
• ~/.aac/credentials/<tenant-id> is the tenant API key. The rendered configuration references it by path.

Everything aac init generates is development material. The development CA lives seven days and the leaf certificates one day. Nothing here qualifies for production, whatever the tenant's domain. Moving to production means a tenant-admin key under production custody (aac tenant rotate-admin-key), a new root key id published by your publisher, and certificates from your approved issuer.

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. <workspace> is the workspace name (default starter) and <tenant-id> the tenant id AAC allocated.

Material	Where	Used for	Lifetime	Back up?
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
tenant_admin_session	~/.aac/credentials/<tenant-id>.session	CLI admin calls	hours; aac sso login	No. sign in again
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); production custody belongs in an HSM/KMS, not a password manager
root_signing_key	~/.aac/workspaces/<workspace>/pki/root.pem, ~/.aac/workspaces/<workspace>/pki/root.pub.pem, ~/.aac/tenants/<tenant-id>/root-keys/<workspace>-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 workspace name)	No. never restore: a replacement workspace gets a new name and therefore a new key id, published alongside the old one until the old one is retired
development_ca	~/.aac/workspaces/<workspace>/ca/dev-ca.key, ~/.aac/workspaces/<workspace>/pki/dev-ca.crt, ~/.aac/workspaces/<workspace>/pair/dev-ca.crt, ~/.aac/tenants/<tenant-id>/spiffe-bundle/<workspace>-dev-ca.ca.pem	signs the workload, terminal and TLS certificates; peers trust it via the published bundle	7 days; aac workspace renew --ca	No. development only; reissue
workload_svid	~/.aac/workspaces/<workspace>/pki/workload.key, ~/.aac/workspaces/<workspace>/pki/workload.crt	the sidecar's SPIFFE identity: proves on every live request that this workload holds the key behind its certificate	1 day; aac workspace renew	No. development only; reissue
terminal_attestation	~/.aac/workspaces/<workspace>/pki/terminal.key, ~/.aac/workspaces/<workspace>/pki/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; kept separate from the workload key so neither can forge the other's role	1 day; aac workspace renew	No. development only; reissue
localhost_tls	~/.aac/workspaces/<workspace>/pki/server.key, ~/.aac/workspaces/<workspace>/pki/server.crt	the sidecar's HTTPS listener	1 day; aac workspace renew	No. development only; reissue
outbound_ca_bundle	~/.aac/workspaces/<workspace>/pki/outbound-ca.pem	the sidecar verifies TLS to AAC and to itself	rebuilt by renew; aac workspace renew	No. derived
pairing_secret	~/.aac/workspaces/<workspace>/pair/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
workspace_manifest	~/.aac/workspaces/<workspace>/manifest.json	the workspace's identities and progress; every workspace verb reads it first	for the life of the workspace	Recommended. cannot be recreated by any command; without it start a new workspace under a new name (see the new-computer setup procedure)
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 workspaces	for the life of the tenant	Recommended. back up with the tenant directory: a replacement workspace 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)
rendered_files	~/.aac/workspaces/<workspace>/sidecar-config.yaml, ~/.aac/workspaces/<workspace>/compose.env, ~/.aac/tenants/<tenant-id>/publisher.env	non-secret configuration derived from the manifest	re-rendered on demand; aac workspace render --force	No. derived; aac workspace render --force recreates them

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 a workspace

aac workspace status --workspace starter --output table   # what exists, expiry, permissions, next command
aac workspace status --workspace starter --remote         # also: is the public trust material visible?
aac workspace renew --workspace starter                   # fresh leaf keys and certificates; old ones archived
aac workspace render --workspace starter --layout container --force   # container path layout

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. render never touches keys and refuses to overwrite rendered files unless --force is given.

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 workspace for the same tenant (--workspace other) reuses the tenant-admin key and gets its own root key id.

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.

   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:

   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. Run the guided setup with a new workspace name. A developer tenant passes its sign-in choice, so an expired session is renewed without a prompt:

   aac init --profile stage --workspace laptop-2 --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 --workspace laptop-2 \
     --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 workspace needs a new name

The workspace name is baked into two identifiers that are published for the whole tenant: the root key id <workspace>-root-v1 and the development CA anchor id <workspace>-dev-ca. 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 workspace name. The new ids are published alongside the old ones until the old ones are retired.

Reusing the old workspace 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

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. An enterprise tenant names its identity-provider connection by the connection's exact URL with --idp-url; when several connections are registered, the error message lists the exact commands to choose one. 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 workspace.
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.

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). 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

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 a hosted trust domain from AAC; registration saves it in the profile, and aac tenant assign-hosted-domain assigns one to a tenant that has none yet. To use your own DNS domain as a trust domain instead, prove control of it with a DNS TXT record, then bind it:

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.