Documentation CLI command reference

CLI Command Reference

This reference is generated from the live Cobra help tree emitted by the aw binary built from cli/go/cmd/aw/. Run scripts/regenerate-cli-reference.sh to refresh it.

Command Families

Family	Commands
Workspace Setup	`check`, `claim-human`, `init`, `reset`, `service`, `workspace`
Identity	`auth`, `custody`, `id`, `mcp-config`, `team`, `whoami`
Messaging & Network	`a2a`, `beads-mail`, `chat`, `contacts`, `control`, `directory`, `events`, `gc-mail`, `heartbeat`, `inbound-mode`, `log`, `mail`, `wake`
Coordination & Runtime	`agent`, `instructions`, `lock`, `notify`, `role-name`, `roles`, `run`, `task`, `work`
Utility	`completion`, `doctor`, `help`, `plugin`, `upgrade`, `version`
Additional Commands	`blueprint`, `session`

Global Flags

--debug Log background errors to stderr
-h, --help help for aw
--identity-home string Use identity authority from this absolute credential root
--json Output as JSON
--server-name string Override the server host or name for this command
--trace Trace redacted HTTP requests and responses to stderr

`check`

Check local identity, workspace, team, and service connectivity.

This is the everyday setup diagnostic entrypoint. It runs the same checks as aw doctor and is safe to run before asking a teammate or support for help.

Flags:

--dry-run Plan fixes without applying them
--fix Apply safe doctor fixes
-h, --help help for check
--offline Run without network checks
--online Allow online checks
--team string Override the selected team_id for this command
--verbose Include verbose diagnostic details

`claim-human`

Attach an email address to your CLI-created account

Flags:

--email string Email address to attach to the current CLI-created account
-h, --help help for claim-human
--mock-url string Override the bootstrap base URL for local development
--username string Override the default dashboard username derived from the registered domain

`init`

Initialize the current directory using one of the supported team-architecture flows:

connect with an existing team certificate already present in .aw/
create a hosted aweb.ai account when this directory is still clean
use –byod to create an identity under a domain you control

By default, init creates or updates the clearly marked aweb section in AGENTS.md or CLAUDE.md. Use –do-not-touch-agents-md to skip that file update.

Flags:

--admission-team-id string Add an agent through host human admission for this explicit team ID
--agent-type string Runtime type (default: AWEB_AGENT_TYPE or agent)
--aweb-url string Base URL for the aweb server used by aw init (overrides AWEB_URL)
--awid-registry string Base URL for the awid registry used by aw init (overrides AWID_REGISTRY_URL)
--byod Use a domain you control instead of hosted aweb.ai onboarding
--do-not-touch-agents-md Do not create or update AGENTS.md or CLAUDE.md during init
--domain string BYOD domain to use with --byod
--expect-account string Expected hosted account ID for workspace-team or admission init
--global Create an addressed self-custodial global identity instead of the default local workspace
-h, --help help for init
--human-name string Human name (default: AWEB_HUMAN or $USER)
--inbound-mode string Inbound delivery mode for a global identity (open|team-and-contacts). Only valid with --global.
--inject-docs Inject aw coordination instructions into CLAUDE.md and AGENTS.md
--join-from string Add an agent to a team by minting one invite from this existing workspace or identity home
--join-team string Team ID to use with --join-from when the source has more than one membership
--name string Identity/member name (global address name with --global, local routing name otherwise)
--new-account Explicitly create a new hosted aweb.ai account
--new-team Explicitly create a new self-hosted/BYOD team
--print-exports Print shell export lines after JSON output
--role string Compatibility alias for --role-name
--role-name string Workspace role name (must match a role in the active team roles bundle)
--setup-channel Set up Claude Code aweb-channel plugin for real-time coordination
--setup-hooks Set up Claude Code PostToolUse hook for aw notify
--url string Base URL for the aweb server used for init, bootstrap, and hosted onboarding flows
--username string Hosted username to create
--workspace-key string OATS canonical format-1 workspace key for --workspace-team
--workspace-team Ensure a workspace's default team using explicit --identity-home and --workspace-key
--write-context Ensure .aw/context exists in the current directory (default true)

`reset`

Removes the local .aw/context and .aw/workspace.yaml files in the current directory without mutating any server-side identity state.

Flags:

-h, --help help for reset

`service`

Connect an existing AWID identity and team certificate to an aw-compatible service.

Service commands do not create identities, register AWID teams, mutate team membership, or call BYOD onboarding flows. Use aw id team register to add a team projection to a service first, then run aw service init from each certified agent workspace.

Subcommands:

init Initialize this workspace against a service using an existing team certificate

Flags:

-h, --help help for service

`service init`

Initialize this workspace against a service using the existing .aw signing key and team certificate in this directory. With –identity-home, initialize and bind the selected external identity root instead of the caller’s current directory. This command only connects this workspace to the service; it does not create identities, create teams, or change AWID team membership.

Flags:

-h, --help help for init
--role string Optional role name for this workspace
--service string Service URL to connect to
--team string Canonical AWID team id to activate before connecting

`workspace`

Manage repo-local coordination workspaces

Subcommands:

add-worktree Legacy convenience: create a sibling git worktree and coordination workspace
connect Connect this workspace to a service using an existing team certificate
delete Delete a local workspace and its local identity, retiring yourself when it is your own
migrate-multi-team Rewrite a legacy single-team workspace into the canonical multi-team shape
status Show coordination status for the current workspace/identity and team

Flags:

-h, --help help for workspace
--team string Override the selected team_id for this command

`workspace add-worktree`

Legacy convenience for existing users: create a sibling git worktree and initialize a new coordination workspace in it.

New setup flows should prefer explicit git worktree/filesystem steps followed by aw init, invite/join, or service init primitives unless this command is reduced to a transparent wrapper with no identity/team orchestration.

Flags:

-h, --help help for add-worktree
--name string Override the default workspace/member name

`workspace connect`

Connect this workspace to a service using the existing .aw signing key and team certificate in this directory.

With –identity-home, connect the selected external identity root and bind the service workspace state under that root, not the caller’s current directory. This is the first-class workspace connection verb. It does not create identities, create teams, or change AWID team membership. It is equivalent to aw service init.

Flags:

-h, --help help for connect
--role string Optional role name for this workspace
--service string Service URL to connect to
--team string Canonical AWID team id to activate before connecting

`workspace delete`

Delete a local workspace and its local identity.

Deleting YOUR OWN workspace on a hosted team, with a local identity, retires you: the hosted team controller revokes your membership certificate, so your name becomes reusable by a later “aw team join”. Any other target is a local delete only, and does not release the name.

Read alias_released in the output, not identity_deleted. Deleting local state says nothing about the membership certificate, and an active certificate is what makes a rejoin under the same name fail. alias_released_reason says why:

not_own_workspace the target is not the workspace you are running as team_not_hosted self-hosted or BYOT; no cloud-held controller to revoke global_identity global identities are retired by team-authorized removal no_workspace_credential no workspace-bound key and no team certificate in local config to authenticate with

When this command can retire you, it does not fall back to a plain delete: a failure is reported as a failure, because a success report for a retirement that did not happen is what leaks names.

With –identity-home, the only destructive operation admitted for an external principal is this own hosted local self-release path. Non-eligible external principals fail closed instead of falling back to generic workspace delete.

Flags:

-h, --help help for delete

`workspace migrate-multi-team`

Rewrite a legacy single-team workspace into the canonical multi-team shape

Flags:

-h, --help help for migrate-multi-team

`workspace status`

Show coordination status for the current workspace/identity and team

Flags:

--all Show all local team memberships in addition to the selected team status
-h, --help help for status
--limit int Maximum team workspaces to show (default 50)

`auth`

Authenticate this host aw CLI to a human aweb account.

Credentials are stored only in the host aw config directory, not in workspace or identity homes.

Subcommands:

login Start browser-based device login for this host aw CLI
logout Revoke host CLI human-auth tokens and remove local credentials
status Show host CLI human-auth status without printing tokens

Flags:

-h, --help help for auth

`auth login`

Start browser-based device login for this host aw CLI

Flags:

-h, --help help for login
--scope string CLI authorization scope (cli.workspace_team|cli.team_admission) (default "cli.workspace_team")
--timeout duration Maximum time to wait for browser approval (default 10m0s)

`auth logout`

Revoke host CLI human-auth tokens and remove local credentials

Flags:

-h, --help help for logout
--scope string CLI authorization scope to revoke (default "cli.workspace_team")

`auth status`

Show host CLI human-auth status without printing tokens

Flags:

-h, --help help for status
--scope string CLI authorization scope to inspect (default "cli.workspace_team")

`custody`

Local resident custody service

Subcommands:

serve Serve local resident custody operations
status Probe local resident custody service
stop Stop local resident custody service

Flags:

-h, --help help for custody

`custody serve`

Serve local resident custody operations

Flags:

-h, --help help for serve

`custody status`

Probe local resident custody service

Flags:

-h, --help help for status

`custody stop`

Stop local resident custody service

Flags:

-h, --help help for stop

`id`

Identity lifecycle, registry, settings, and key management

Subcommands:

address Manage addresses for the current global identity
addresses List registry addresses for a did:aw (defaults to the current global identity)
cert Team certificate operations
create Create a global identity by claiming a namespace address
encryption-key Manage local E2E encryption keys for this self-custodial identity
grant Scoped, expiring session grants derived from this identity
log Show a global AWID DID log
namespace Protocol/admin namespace controller and address operations
register Register the current global identity at the configured registry
request Make a DIDKey-signed HTTP request with the local identity key
resolve Resolve a did:aw to its current did:key
rotate-key Rotate the current global identity signing key at the registry
show Show the current identity and registry status
sign Sign a canonical JSON payload with the local identity key
team Team membership plus protocol/admin certificate operations
verify Verify the full audit log for a did:aw

Flags:

-h, --help help for id

`id address`

Manage addresses for the current global identity

Subcommands:

claim Claim an additional address for the current global identity

Flags:

-h, --help help for address

`id address claim`

Claim an additional address for the current global identity

Flags:

-h, --help help for claim
--registry string Registry origin override

`id addresses`

List registry addresses for a did:aw (defaults to the current global identity)

Flags:

-h, --help help for addresses

`id cert`

Team certificate operations

Subcommands:

show Show the current team certificate

Flags:

-h, --help help for cert

`id cert show`

Show the current team certificate

Flags:

-h, --help help for show

`id create`

Create a self-custodial global identity in .aw/ by claiming DOMAIN/NAME in a namespace you control. This mints a did:aw, stores the local signing key material, and atomically claims the global address in AWID.

Flags:

--domain string Namespace domain for the global identity address
-h, --help help for create
--name string Global identity name (address name under --domain)
--registry string Registry origin override (default: api.awid.ai)
--skip-dns-verify Skip the DNS TXT verification prompt and lookup

`id encryption-key`

Manage local E2E encryption keys for this self-custodial identity

Subcommands:

rotate Rotate the local E2E encryption key while keeping archived keys
setup Create or publish the local E2E encryption key for this identity
show Show local E2E encryption key state

Flags:

-h, --help help for encryption-key

`id encryption-key rotate`

Rotate the local E2E encryption key while keeping archived keys

Flags:

-h, --help help for rotate

`id encryption-key setup`

Create or publish the local E2E encryption key for this identity

Flags:

-h, --help help for setup

`id encryption-key show`

Show local E2E encryption key state

Flags:

-h, --help help for show

`id grant`

Scoped, expiring session grants derived from this identity

Subcommands:

list List this identity’s session grants
mint Mint a session grant and write a self-contained grant home
revoke Revoke a session grant
show Show one session grant

Flags:

-h, --help help for grant
--team string Override the selected team_id for this command

`id grant list`

List this identity’s session grants

Flags:

-h, --help help for list

`id grant mint`

Mint a session grant and write a self-contained grant home

Flags:

--app-tool stringArray Installed app tool the grant may call, as app:verb; repeatable or comma-separated. Each signed tool must be named; the definition is snapshotted at mint
--bundle stringArray Grant scope bundle, repeatable or comma-separated (normal-agent)
--custody-socket string Resident custody Unix socket path to write into grant.yaml, or auto for the resident identity home's default custody socket
-h, --help help for mint
--label string Optional label for the grant
--out string Directory to write the grant home (created fresh; a non-empty directory is refused)
--scope stringArray Grant scope, repeatable or comma-separated (mail.read, mail.send, chat.read, chat.send, events.read, coord.read, coord.write, presence.write, contacts.read, contacts.write)
--ttl duration Grant duration before expiry (60s to 720h) (default 8h0m0s)

`id grant revoke`

Revoke a session grant

Flags:

-h, --help help for revoke

`id grant show`

Show one session grant

Flags:

-h, --help help for show

`id log`

Show the AWID registry DID log for a global identity. The log records DID registration and key-rotation entries, verifies the returned chain, and reports the current did:key head.

Without arguments, the command reads the current global identity’s did:aw. An explicit target may be a did:aw or a global address in / form, which is resolved through the registry before reading its DID log. Local identities do not have registry-backed history; the command returns unsupported_registry_history for a current local identity instead of inventing hosted history.

With –json, status is OK for a verified log, BROKEN for unverifiable log data or address/log key mismatch, UNREACHABLE for registry fetch failures, and unsupported_registry_history for local identities.

Flags:

-h, --help help for log

`id namespace`

Protocol/admin namespace controller and address operations.

Use these commands when you hold a namespace controller key, are setting up BYOT, are assigning or deleting namespace addresses, or are diagnosing AWID registry state. Hosted happy-path setup should not require namespace controller commands.

Subcommands:

addresses List registry namespace addresses
assign-address Assign a namespace address to an existing did:aw using the local controller key
check-txt Verify the _awid DNS TXT record matches the local namespace controller key
delete Delete an AWID namespace using the local controller key
delete-address Delete a namespace address claim using the local controller key
prepare-controller Create or show a local namespace controller key and DNS TXT value
resolve Resolve a registry namespace address
rotate-controller Recover namespace control by rotating to a new controller key
set-delivery-origin Set namespace address-route default delivery origin using the local controller key

Flags:

-h, --help help for namespace

`id namespace addresses`

List registry namespace addresses

Flags:

--authority string Authority mode: anonymous, did, or namespace-controller (default "anonymous")
-h, --help help for addresses

`id namespace assign-address`

Assign a namespace address to an existing did:aw using the local controller key

Flags:

--did-aw string Existing did:aw to bind the address to
--domain string Namespace domain (e.g. aweb.ai)
-h, --help help for assign-address
--name string Address name (e.g. alice)

`id namespace check-txt`

Verify the _awid DNS TXT record matches the local namespace controller key.

This is read-only. It looks up _awid., loads the local namespace controller key from ~/.awid/controllers/.key (or –controller-key), and fails if DNS has not propagated or points at a different controller DID.

Flags:

--controller-key string Namespace controller key path override
--domain string Namespace domain
-h, --help help for check-txt

`id namespace delete`

Delete an AWID namespace using the local namespace controller key.

Namespace deletion requires all active certificates in the namespace to be revoked first. It does not update DNS; remove any _awid TXT record at your DNS provider after the registry delete succeeds. Local controller/team key files are preserved unless –purge-local is set, in which case they are moved to ~/.awid/deregister-backups/ instead of being unlinked.

Flags:

--domain string Namespace domain (e.g. aweb.ai)
-h, --help help for delete
--purge-local Move local controller and team keys for the namespace to ~/.awid/deregister-backups after successful registry delete
--reason string Optional deletion reason recorded by the registry
--registry string Registry origin override

`id namespace delete-address`

Delete a namespace address claim using the local namespace controller key.

This removes the address route/claim, not the append-only did:aw audit log. If the address has active team certificates, revoke those certificates first.

Flags:

--domain string Namespace domain (e.g. aweb.ai)
-h, --help help for delete-address
--name string Address name (e.g. alice)
--reason string Optional deletion reason recorded by the registry
--registry string Registry origin override

`id namespace prepare-controller`

Create or show a local namespace controller key and DNS TXT value.

This command is deliberately local-only: it writes the namespace controller key under ~/.awid/controllers and prints the _awid TXT record to publish. Keep ~/.awid safe and backed up; losing this key means losing direct namespace controller authority unless you recover via DNS. It does not call AWID, create a did:aw identity, claim an address, create a team, or modify aweb Cloud state.

Flags:

--domain string Namespace domain
-h, --help help for prepare-controller
--registry string Registry origin to place in the DNS TXT record (default: api.awid.ai or AWID_REGISTRY_URL)

`id namespace resolve`

Resolve a registry namespace address

Flags:

--authority string Authority mode: anonymous, did, or namespace-controller (default "anonymous")
-h, --help help for resolve

`id namespace rotate-controller`

Recover namespace control by rotating to a new controller key

Flags:

--domain string Namespace domain to rotate
-h, --help help for rotate-controller

`id namespace set-delivery-origin`

Set namespace address-route default delivery origin using the local controller key

Flags:

--domain string Namespace domain (alias for --namespace)
-h, --help help for set-delivery-origin
--namespace string Namespace domain (e.g. acme.com)
--origin string Canonical aweb server origin (e.g. https://aweb.acme.com)

`id register`

Flags:

-h, --help help for register

`id request`

Make a DIDKey-signed HTTP request with the local identity key

Flags:

--body string Request body to send. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --body-file for Markdown or command examples
--body-file string Read request body from a file; safe for Markdown or command examples
--header stringArray Additional header in 'Name: Value' form
-h, --help help for request
--raw Print only the upstream response body
--sign string JSON object describing the signed payload fields
--sign-file string Read the JSON sign payload from a file
--team-auth Attach the active team certificate and sign a team-bound request payload

`id resolve`

Resolve a did:aw to its current did:key

Flags:

-h, --help help for resolve

`id rotate-key`

Rotate the current global identity signing key at the registry

Subcommands:

recover Reconcile and safely finish a pending identity key rotation
status Inspect pending identity key rotation state without changing it

Flags:

-h, --help help for rotate-key

`id rotate-key recover`

Reconcile and safely finish a pending identity key rotation

Flags:

-h, --help help for recover

`id rotate-key status`

Inspect pending identity key rotation state without changing it

Flags:

-h, --help help for status

`id show`

Show the current identity and registry status

Flags:

-h, --help help for show

`id sign`

Sign a canonical JSON payload with the local identity key

Flags:

-h, --help help for sign
--payload string JSON object to sign
--payload-file string Read the JSON payload to sign from a file

`id team`

Team membership plus protocol/admin certificate operations.

Everyday hosted setup normally uses invite and accept-invite. Controller-backed commands such as create, add-member, remove-member, register, import-request, cleanup-cloud, and delete are protocol/admin primitives for BYOT, controller holders, service projection, or diagnostics.

Subcommands:

accept-invite Accept a team invite and receive a membership certificate
add-member Protocol/admin: add a member by signing a team certificate
cleanup-cloud Protocol/admin: delete aweb Cloud’s BYOT projection after registry team deletion
create Protocol/admin: create a customer-controlled AWID team
delete Protocol/admin: delete an AWID team using the namespace controller key
fetch-cert Protocol/admin bridge: fetch and install an approved team certificate
import-request Protocol/admin: create a signed BYOT import request for aweb cloud
invite Generate an invite token for a team
leave Remove a team membership from this identity
list List team memberships for this identity
members List a team’s members from AWID certificates
register Protocol/admin: register or sync a customer-controlled team with a service
reissue-cert Protocol/admin: mint and register a fresh certificate for the same member key
remove-member Protocol/admin: remove a member by revoking a team certificate
request Protocol/admin bridge: print the add-member command the team owner should run
switch Switch the active team for this identity

Flags:

-h, --help help for team

`id team accept-invite`

Accept a team invite and receive a membership certificate.

Scope is explicit: –local is the default, and –global reuses the existing self-custodial global identity in this workspace. –address never selects global scope; pass –global when presenting an existing owned address.

Hosted aw_inv_ tokens are redeemed through the cloud. Local hosted accepts create a fresh local signing key and refuse to overwrite completed local state. Global hosted accepts reuse identity.yaml’s stored did:aw and signing key; they do not mint a new did:aw just because this identity joins another team. Hosted –global accepts may use –address for an owned address or –no-address for did:aw-only membership. External –identity-home hosted local accepts connect that root to the issuing service when the invite names one; if connection fails, rerun the printed aw --identity-home <root> workspace connect --service <url> recovery command without reusing the invite. Other membership-only accepts can be connected later with aw init or aw workspace connect.

Local-controller invite tokens are same-machine helpers: they require the local invite record and local team controller key. Local-controller global accepts default-claim team-domain/name only when the local namespace controller key is also present; otherwise use –address for an owned address or –no-address for did:aw-only membership. For cross-machine BYOT joins, use aw id team request, have the controller run aw id team add-member, then install with aw id team fetch-cert on the joining machine.

Flags:

--address string Advanced: existing owned address to place in the global member certificate
--global Join by reusing the existing global identity in this workspace
-h, --help help for accept-invite
--local Join with a local workspace identity (default)
--name string Member name for the accepting agent (defaults to identity name)
--no-address For --global, join with did:aw continuity but no member address

`id team add-member`

Protocol/admin: add a member by signing a team certificate

Flags:

--address string Global member address when using --did; must resolve to --did-aw
--did string Member did:key for direct certificate issuance
--did-aw string Optional stable did:aw when using --did
--global Issue a global member certificate for --did
-h, --help help for add-member
--local Issue a local workspace member certificate for --did (default)
--member string Member address (e.g. acme.com/alice)
--name string Member name to use with --did
--namespace string Namespace domain
--team string Team name

`id team cleanup-cloud`

Delete aweb Cloud’s imported BYOT team projection using customer-held controller authority.

This command does not mutate AWID. In the normal path it signs the cleanup request with ~/.awid/team-keys//.key so aweb Cloud can verify that the customer-controlled team controller authorized the projection delete. If the team controller key has already been retired, use –namespace-controller to sign with the namespace controller key; aweb Cloud will verify that key against the _awid. DNS TXT controller for the team’s domain, with AWID registry lookup as a fallback when DNS is absent.

Flags:

--apply Apply the cleanup instead of dry-run
--aweb-url string aweb Cloud URL (default "https://app.aweb.ai")
-h, --help help for cleanup-cloud
--namespace string Namespace domain
--namespace-controller Authorize cleanup with the namespace controller key instead of the team controller key
--namespace-key string Namespace controller key path override for --namespace-controller
--team string Team name
--team-key string Team controller key path override
--timestamp string RFC3339 timestamp to sign (defaults to now; accepted for five minutes by cloud)

`id team create`

Protocol/admin: create a customer-controlled AWID team

Flags:

--display-name string Team display name
-h, --help help for create
--name string Team name
--namespace string Namespace domain
--registry string Registry origin override

`id team delete`

Protocol/admin: delete an AWID team using the local namespace controller key.

Delete-team requires the team’s active certificates to be revoked first. It does not delete the namespace or any unrelated address claims.

Flags:

-h, --help help for delete
--namespace string Namespace domain
--reason string Optional deletion reason recorded by the registry
--registry string Registry origin override
--team string Team name

`id team fetch-cert`

Protocol/admin bridge: fetch and install an approved team certificate

Flags:

--cert-id string Certificate id
--force Overwrite an existing local certificate for the team
-h, --help help for fetch-cert
--namespace string Namespace domain
--registry string Registry origin override
--team string Team name

`id team import-request`

Create a signed BYOT import request for aweb cloud.

This command signs the canonical import payload with your local BYOT team controller key. It prints the request body expected by POST /api/v1/teams/byoidt/import. It never uploads or prints namespace or team controller private keys. The cloud import endpoint accepts the signed timestamp for five minutes; regenerate the request body after it expires.

Flags:

--apply Create an apply request instead of the default dry-run request
--cloud-team-id string Existing AC team id to sync
-h, --help help for import-request
--namespace string Namespace domain
--organization-id string AC organization id for a new imported team
--team string Team name
--timestamp string RFC3339 timestamp to sign (defaults to now; accepted for five minutes by cloud)

`id team invite`

Generate an invite token for a team.

Defaults to the active local team when –team and –namespace are omitted. Invites create local workspace members unless –member-global is set. Hosted teams use cloud invite authority; local-controller teams use the local team controller key.

Flags:

-h, --help help for invite
--member-global Create global member invite
--member-local Create local workspace member invite (default)
--namespace string Namespace domain
--team string Team name

`id team leave`

Remove a team membership from this identity

Flags:

-h, --help help for leave

`id team list`

List team memberships for this identity

Flags:

-h, --help help for list

`id team members`

List a team’s members from AWID certificates.

Membership is represented by team certificates, so this identity-level command lists the certificate roster for the selected team. By default it shows active certificates; pass –include-revoked to include revoked rows.

Flags:

-h, --help help for members
--include-revoked Include revoked membership certificates
--namespace string Namespace domain; defaults to active team namespace
--registry string Registry origin override
--team string Team name; defaults to active team name
--team-id string Canonical team id (<team>:<namespace>); defaults to active team

`id team register`

This command is service-generic: it signs a registration request with the local team controller key and sends only public/signed team facts to the service. It never uploads namespace or team controller private keys and does not initialize any agent workspace. Services may return their own next steps, such as aw service init or aw claim-human.

Flags:

--dry-run Preview registration without mutating the service projection
-h, --help help for register
--registry string Registry origin override
--service string Service URL to register with
--team string Canonical AWID team id (<team>:<namespace>)
--timestamp string RFC3339 timestamp to sign (defaults to now; accepted for five minutes by service)

`id team reissue-cert`

Mint, register, and (optionally) install a fresh team certificate for an existing member, keeping the member’s did:key, alias, and identity scope unchanged.

This is the remedy for a lost or never-registered certificate blob: the signed blob cannot be reconstructed, so the team controller signs a fresh certificate (new certificate id, fresh issued_at) for the same member key. If the registry holds an active certificate for the alias, it is revoked first and the fresh one is registered after, so the registry’s one-active-certificate-per-alias constraint is never violated. If none is registered, the fresh certificate is simply registered. Re-running after a partial failure is safe: a run that revoked but died before registering finds no active certificate and registers; a run against an already-reissued member revokes the current certificate and swaps in a fresh one.

Revoking the old certificate invalidates any grants issued under it, and the member’s server projection refreshes at its next certificate-authenticated connect, so expect the member to reconnect.

This is NOT key rotation: the member keeps its did:key, and the command refuses to run when the registered member key differs from the one attested. For a lost or compromised member KEY, use aw team admin replace-key instead.

Requires the locally-held team controller key (BYOT/local-controller teams). Hosted aweb.ai teams keep the controller key in cloud custody; hosted re-issuance runs through the hosted service or operator support.

Pass –home to verify the member’s local home and install the fresh blob there; without –home the command prints the blob and where the member must place it.

Flags:

--address string Global member address when no registered certificate states it; requires --did-aw
--did string Member did:key the fresh certificate binds (required unless --home is supplied)
--did-aw string Global member did:aw when no registered certificate states it
--global Assert global identity scope
-h, --help help for reissue-cert
--home string Member home whose signing key attests the did:key and where the fresh certificate is installed
--local Assert local identity scope (default when no registered certificate states it)
--namespace string Namespace domain
--registry string Registry origin override
--team string Team name

`id team remove-member`

Protocol/admin: remove a member by revoking a team certificate

Flags:

--api-key string Team API key for hosted removal (overrides AWEB_API_KEY; workspace-bound API keys are rejected by hosted aweb)
--aweb-url string Hosted aweb API URL override for cloud-mediated removal
--cert-id string Certificate id to revoke (hosted remove accepts --member or --cert-id)
-h, --help help for remove-member
--member string Member address (e.g. acme.com/alice)
--namespace string Namespace domain
--registry string Registry origin override
--team string Team name

`id team request`

Protocol/admin bridge: print the add-member command the team owner should run

Flags:

-h, --help help for request
--name string Suggested member name for the new team membership
--team string Canonical team ID (<name>:<domain>)

`id team switch`

Switch the active team for this identity

Flags:

-h, --help help for switch

`id verify`

Verify the full audit log for a did:aw

Flags:

-h, --help help for verify

`mcp-config`

Output MCP server configuration for the current identity

Flags:

--channel Output stdio channel config instead of HTTP MCP config
-h, --help help for mcp-config

`team`

Everyday team membership commands.

Use these commands to invite a member, join or leave a team, and inspect or switch this identity’s installed memberships. Local agent orchestration, profile management, and owner/admin repair operations live under aw team admin.

Subcommands:

admission-invite Issue a shared-team admission invite token
ensure Ensure this host has a workspace’s default team authority
invite Invite an agent or workspace to the active team
join Join a team from an invite token
leave Remove a team membership from this identity
list List team memberships for this identity
spawn-authority Check whether the selected identity can create hosted spawn invites
switch Switch the active team for this identity
admin Experimental local orchestration and team administration

Flags:

-h, --help help for team

`team admission-invite`

Issue a shared-team admission invite token.

This uses host CLI auth with scope cli.team_admission to request an ordinary single-use aw_inv_ token for a chosen recipient. It does not accept the invite, install membership, or bind this workspace; use aw team join or aw id team accept-invite with the returned token in the target identity root.

Flags:

--alias-hint string Optional suggested member alias for the recipient
--expect-account string Expected hosted account ID issuing this admission invite
-h, --help help for admission-invite
--request-id string Client-generated UUID for retry-safe issuance
--team-id string Cloud team UUID or canonical AWID team ID to issue an admission invite for

`team ensure`

Ensure this host has a workspace’s default team authority.

The server receives only the format-1 workspace-key digest. Credentials are installed only into the explicit –identity-home credential root, and the result is bound only after a live spawn-authority proof from that installed root.

Stable diagnostics are printed to stderr and exit 2, including with –json; there is no JSON error envelope. authorization-required means host CLI auth is missing, invalid, expired, revoked, or not authorized. workspace-key-not-portable means a local/ workspace key cannot be used for hosted default team ensure. identity-home-occupied means the explicit identity home already contains conflicting identity, team, workspace, or binding state. unsupported-server means the aweb service is older than the workspace’s default team ensure/enroll contract (Cloud 0.8.16 or later) and is missing one of: CLI auth status, workspace’s default team ensure, workspace’s default team enroll, or installed-root spawn-authority proof. Non-404 server errors keep their existing handling.

Flags:

--expect-account string Expected hosted account ID that owns this workspace's default team
-h, --help help for ensure
--label string Optional display label for the workspace's default team
--workspace-key string OATS canonical format-1 workspace key

`team invite`

Invite an agent or workspace to the active team.

This creates an invite token using the current team’s authority for a separate workspace or machine, then the joining workspace runs aw team join <token>. For local empty-profile homes under agents/instances/, use aw team admin add.

Flags:

-h, --help help for invite
--member-global Create global member invite
--member-local Create local workspace member invite (default)
--team-id string Canonical team id (<name>:<namespace>) to invite from (defaults to active team)

`team join`

Join a team from an invite token.

Run this in a clean target directory. It refuses to overwrite an existing .aw identity/key. Join installs the identity and membership, then connects this workspace to the aweb service carried by the invite. Use –no-connect only when you intentionally want identity state without a workspace binding.

Flags:

--address string Advanced: existing owned address to place in the global member certificate
--global Join by reusing the existing global identity in this workspace
-h, --help help for join
--local Join with a local workspace identity (default)
--name string Member name for the accepting agent (defaults to identity name)
--no-address For --global, join with did:aw continuity but no member address
--no-connect Install identity and membership without connecting this workspace

`team leave`

Remove a team membership from this identity

Flags:

-h, --help help for leave

`team list`

List team memberships for this identity

Flags:

-h, --help help for list

`team spawn-authority`

Check hosted spawn authority for the selected identity and team.

This is a read-only proof against /api/v1/spawn/authority. It does not use or prove CLI human auth status.

Flags:

-h, --help help for spawn-authority
--team-id string Canonical team id to check (defaults to selected team)

`team switch`

Switch the active team for this identity

Flags:

-h, --help help for switch

`team admin`

Experimental local orchestration and team administration.

Use this surface to materialize or launch local agent homes, manage their pinned profiles, or perform owner/admin inspection and repair. These operations are separate from the everyday invite, join, list, switch, and leave journey.

Subcommands:

add Add agents to this team’s agents/instances layout
adopt Adopt a public-pinned agent profile onto the team’s private Library shelf
create Create a local empty-profile team workspace
extend Add agents to an existing team by discovering membership authority
refresh Refresh a team member’s profile and existing team-instructions block
up Launch local team agents in tmux
agent-status Read whether an agent still holds a certificate, a workspace, or task claims
remove-agent Retire an agent: release its claims, then revoke its certificate
replace-key Replace a local agent identity key under team-controller authority

Flags:

-h, --help help for admin

`team admin add`

Add one or more agents to agents/instances//. Specs use [NAME@]BLUEPRINT/PROFILE[:local|global][=RUNTIME] or NAME[:local|global] for empty-profile homes. Omitted names use the server-authoritative next classic name; omitted scope comes from profile.yaml. @VERSION is no longer supported.

Flags:

--attach Attach or switch to the tmux session after --start launch (default true)
--blueprint string Default public Library blueprint for profile-only selectors (default: AWEB_BLUEPRINT or aweb.team)
--global Add a global AWID identity/address-backed agent
-h, --help help for add
--home string Agent home directory override for a single added agent (default: agents/instances/<name>)
--layout-only Only create agents/instances/<name>; do not create identity state
--library-url string Public Library catalog base URL (default: AWEB_LIBRARY_URL or https://library.aweb.ai)
--local Add a local team-scoped agent identity (default)
--no-attach Do not attach or switch to the tmux session after --start launch
--runtime string Materialization runtime for profile-bound agents (claude-code|codex|pi|local-shell; default claude-code)
--session string tmux session name for --start (default: caller's session inside tmux, otherwise active team name or aw-team)
--start Launch the added agent in tmux after materializing it
--work-dir string Git repo to use for the agent's worktree (default: repo containing the home, if any)

`team admin adopt`

Adopt a public-pinned agents/instances/ profile onto the team’s private Library shelf. This reads .aw/profile/ref.json, imports the pinned public blueprint/profile onto the team shelf through the installed Library plugin, binds the agent, and re-points the local pin to the shelf copy by removing library_url. After adopt, aw team admin refresh uses the shelf path and can pick up approved team-local profile mints.

Flags:

-h, --help help for adopt
--home string Agent home directory override (default: agents/instances/<name>)

`team admin create`

Create a local empty-profile team workspace.

This wraps aw init for the aw-local path. No –agent/–profile means no Library call and no profile materialization. –agent accepts [NAME@]BLUEPRINT/PROFILE[:local|global][=RUNTIME] (or NAME[:local|global] for an empty-profile agent). Omitted names use the server-authoritative next classic name; omitted scope comes from profile.yaml. All –agent/–profile specs populate agents/instances for aw team admin up; only –home with a single spec uses that spec for the root workspace profile. Deprecated –profile is accepted as –agent for transition; @VERSION is dropped.

Flags:

--agent stringArray Agent spec [NAME@]BLUEPRINT/PROFILE[:local|global][=RUNTIME] or NAME[:local|global]
--blueprint string With --agent/--profile, default public Library blueprint for profile-only selectors; without agents, materialize all profiles in a local blueprint directory
--byot Create a customer-controlled AWID team with local namespace controller authority
--display-name string Team display name
--first-agent-global Enroll the first agent as a global identity, reusing an existing global identity or creating one when founding with hosted/namespace authority
--first-agent-local Enroll the first agent as a local team-scoped identity (default)
--first-agent-name string Initial workspace member name (defaults to <name>)
-h, --help help for create
--home string Agent home directory override for single-agent --profile create
--library-url string Public Library catalog base URL (default: AWEB_LIBRARY_URL or https://library.aweb.ai)
--name string Team name
--namespace string Namespace domain for --byot
--profile stringArray Deprecated alias for --agent; use [NAME@]BLUEPRINT/PROFILE[:local|global][=RUNTIME]
--registry string Registry origin override for --byot
--runtime string Materialization runtime for agent/profile homes (claude-code|codex|pi|local-shell; default claude-code)
--service string Hosted service URL for dashboard guidance
--username string Hosted username to create when founding through managed aweb onboarding

`team admin extend`

Add agents to an existing team by discovering membership authority. Specs use [NAME@]BLUEPRINT/PROFILE[:local|global][=RUNTIME] or NAME[:local|global] for empty-profile homes. Explicit –api-key or –team-id with AWEB_API_KEY wins. An ambient AWEB_API_KEY in a workspace with an active team uses that team as an assertion against the API key’s team; explicit –api-key bypasses the workspace assertion.

Flags:

--api-key string Team API key for extending a team (overrides AWEB_API_KEY)
--attach Attach or switch to the tmux session after --start launch (default true)
--blueprint string Default public Library blueprint for profile-only selectors (default: AWEB_BLUEPRINT or aweb.team)
--global Add a global AWID identity/address-backed agent
-h, --help help for extend
--library-url string Public Library catalog base URL (default: AWEB_LIBRARY_URL or https://library.aweb.ai)
--local Add a local team-scoped agent identity (default)
--no-attach Do not attach or switch to the tmux session after --start launch
--runtime string Materialization runtime for profile-bound agents (claude-code|codex|pi|local-shell; default claude-code)
--session string tmux session name for --start (default: caller's session inside tmux, otherwise active team name or aw-team)
--start Launch the added agent in tmux after materializing it
--team-id string Canonical team id (<name>:<namespace>) to extend when discovery is ambiguous or when asserting an API key's team
--work-dir string Git repo to use for the agent's worktree (default: repo containing the home, if any)

`team admin refresh`

Re-materialize agents/instances/ from the latest version of the profile it was materialized from on the team’s private Library shelf. This closes the learning loop: an approved profile proposal mints a new shelf version, and aw team admin refresh re-applies it locally and updates .aw/profile/ref.json - so the agent picks up the team’s own improvement. It reads the recorded profile ref locally and never asks a remote service which profile to use.

When the home already has exactly one complete AWEB:START/AWEB:END block, refresh also re-injects the active team instructions. It never creates that block in an unmarked home; use aw instructions inject <directory> when an explicit backfill is intended.

Upstream blueprint updates are a separate, composable step: run aw library update-from-source first to pull them onto the shelf, then aw team admin refresh to re-materialize.

Flags:

-h, --help help for refresh
--home string Agent home directory override (default: agents/instances/<name>)
--runtime string Runtime harness to re-materialize for (claude-code|codex|pi|local-shell) (default "claude-code")

`team admin up`

Launch local team agents in tmux. This is a local runtime convenience: it reads materialized agents/instances/ homes and starts one tmux window per supported interactive harness. Team definitions and profile provenance remain in aweb state and .aw/profile/ref.json.

Flags:

--attach Attach or switch to the tmux session after launch (default true)
--dry-run Print the tmux launch plan without running it
--force Start even when another process already has an agent home as its cwd
--force-kill Allow --recreate to kill a tmux session that contains running agent windows
-h, --help help for up
--no-attach Do not attach or switch to the tmux session after launch
--recreate Kill and recreate an existing tmux session
--session string tmux session name (default: caller's session inside tmux, otherwise active team name or aw-team)

`team admin agent-status`

Read the state of one agent across the stores retirement has to clear.

This reads and never writes. It exists so that the evidence an agent is retired comes from somewhere other than the command that retired it.

Flags:

-h, --help help for agent-status
--team-id string Canonical team id (<name>:<namespace>) to read from (defaults to active team)

`team admin remove-agent`

Retire an agent from a team across the stores that hold its state.

It first deletes the agent’s workspace record, which releases the task claims held under it, and only then revokes its certificate. That order matters: an agent can release its own claims until its certificate is revoked, and the legacy hosted remove-member path can delete the same workspace record without releasing anything. The prepared hosted-local path preserves the same order.

If the claims cannot be released the command stops before revoking and says which store changed and which did not, rather than leaving an agent with no credential and claims nobody can clear. To revoke access immediately and accept that outcome, use aw id team remove-member.

Customer-controlled teams revoke with the local team controller key. Hosted local members first prepare an immutable workspace/agent/certificate operation, persist non-secret recovery state, release exact coordination state, and commit cloud-mediated revocation. Use –resume-operation after a partial failure, –list-pending when local recovery state is lost, or –abort-operation only before release. Addressed/global hosted members retain the exact-certificate path.

STATUS VALUES. These are a contract; branch on them rather than on the prose. Each says what its evidence supports, and the second column is the part that matters, because the defect this command was built to remove was a status word asserting more than the service had established.

status (whole retirement) retired every store reached the state retirement wants, and each one established it. Exit 0. reported_retired every store reached that state, but the certificate part rests on a service reporting a no-op. It does NOT mean no certificate exists. Exit 0. Confirm with agent-status. incomplete a store did not reach that state; the per-store results say which. Exit non-zero.

certificate_result revoked this call revoked a certificate. already_revoked the registry stated the certificate exists and was already revoked. Only a registry says this; it is never inferred from an absence. reported_nothing_to_revoke the service reported it had nothing to revoke. This says NOTHING about whether a certificate exists: the hosted service answers from its own membership records and may never consult the registry, so a member holding a live certificate with no hosted record is reported this way.

per-store result: changed, unchanged, blocked, failed, not_attempted. changed and unchanged are terminal; the other three are not.

claims_released is null when the server did not report a count, which is what a server older than that field does. Null is not zero.

Exit status answers one question only: did the request reach the service and get an answer. It never carries a claim about certificate state. So on a customer-controlled team, retiring a name that no longer resolves is an error rather than a no-op, because that answer is indistinguishable from a request that never arrived - while a registry saying already-revoked is success.

Flags:

--abort-operation string Abort exact hosted removal operation ID before coordination release
--api-key string Team API key for hosted removal (overrides AWEB_API_KEY; workspace-bound API keys are rejected by hosted aweb)
--aweb-url string Hosted aweb API URL override for cloud-mediated removal
-h, --help help for remove-agent
--list-pending List owner/admin hosted removal operations requiring recovery
--registry string Registry origin override
--resume-operation string Resume exact hosted removal operation ID; no member address is accepted
--team-id string Canonical team id (<name>:<namespace>) to remove from (defaults to active team)

`team admin replace-key`

Replace a local team-scoped agent’s did:key under locally-held team-controller authority.

This compare-and-swap operation updates the service roster, revokes the old team certificate, registers a new certificate, and records the controller-authorized transition. When a real local home has lost signing.key, –generate-new-key creates and retains a replacement key without overwriting an existing one. Hosted teams require the pending AC owner/admin integration or operator support.

Flags:

--aweb-url string Aweb service URL override
--generate-new-key Generate a replacement signing key in --home when signing.key is absent (cannot be combined with --new-did-key)
-h, --help help for replace-key
--home string Agent home whose new signing identity is verified and where the replacement certificate is installed
--new-did-key string Replacement local member did:key (required unless --generate-new-key is used)
--old-cert-id string Old team certificate id (required without --home)
--old-did-key string Expected current local member did:key (required)
--registry string AWID registry URL override
--team-id string Canonical team id (<name>:<namespace>; defaults to active team)

`whoami`

Show the current identity

Flags:

-h, --help help for whoami
--team string Override the selected team_id for this command

`a2a`

Inspect and call A2A agents

Subcommands:

cancel Cancel an A2A task
card Fetch and verify an A2A Agent Card
publish Publish an A2A Agent Card route to AWID
send Send a task message to an A2A agent
status Fetch an A2A task

Flags:

-h, --help help for a2a

`a2a cancel`

Cancel an A2A task

Flags:

-h, --help help for cancel

`a2a card`

Fetch and verify an A2A Agent Card

Flags:

--address string aweb address to verify through AWID, e.g. acme.com/help
-h, --help help for card
--registry-url string AWID registry URL for verification

`a2a publish`

Publish an A2A Agent Card route to AWID

Flags:

--address string aweb address to publish; defaults to current identity address
--assertion-id string Publication assertion id override
--card-revision string Card revision recorded in AWID; defaults to Agent Card version
--default-for-host Mark this route as the default A2A route for the host
--delegation-id string Bridge delegation id override
--expires-days int Publication/delegation lifetime in days (default 30)
--gateway-identity string did:aw of the A2A gateway identity; defaults to current identity for direct publication
-h, --help help for publish
--registry-url string AWID registry URL override
--route-id string Route id override; defaults to the card URL route
--rpc-url string RPC URL override; defaults to supportedInterfaces[0].url

`a2a send`

Send a task message to an A2A agent. Warning: double-quoted shell arguments expand backticks and $(…) before aw runs; use –body-file for Markdown or command examples

Flags:

--body-file string Read message body from a file; safe for Markdown or command examples
--context string A2A context ID
--data string Additional JSON metadata object
-h, --help help for send
--no-wait Return immediately after task creation
--wait Wait for terminal or interrupted task state

`a2a status`

Fetch an A2A task

Flags:

-h, --help help for status
--history int History length to request; -1 uses server default (default -1)

`beads-mail`

Mail for beads, no orchestrator required.

beads ships a ‘bd mail’ command that delegates to an external mail provider. This is that provider, backed by aweb: durable delivery, offline recipients, and cryptographically verified sender identity.

Setup, once per repo:

npm i -g @awebai/aw aw init bd config set mail.delegate “aw beads-mail”

Then ‘bd mail send’, ‘bd mail inbox’, and friends work. Recipients run the same three lines. Map beads-style names to aweb addresses in .beads/aweb-mail.toml; addresses containing a domain (acme.com/reviewer) need no mapping.

Two things to know that differ from ‘gt mail’:

‘bd mail’ swallows –help anywhere in the arguments, so use ‘bd mail help ’ (or ‘aw beads-mail –help’) for per-verb help.
‘bd mail check’ always exits 0 when the probe worked; branch on its output or –json, not the exit code. Nonzero means a real failure.

Optional in-session wake-ups when mail arrives: aw init –setup-channel.

Subcommands:

announces Not supported in v1
archive Not supported: the beads graph is the archive
check Check for unread mail (for hooks)
claim Not supported in v1: no message queues
clear Not supported: server mail expires on its own
delete Not supported: server mail expires on its own
drain Not supported in v1
help Show help for a beads-mail verb (‘bd mail’ swallows –help; this reaches us)
inbox List unread messages (read-only; reading is what marks read)
mark-read Mark messages as read
mark-unread Not supported: read state cannot be cleared
peek Preview the first unread message without marking it read
read Read a message and mark it read
release Not supported in v1: no message queues
reply Reply to a message
search Not supported in v1: no server-side mail search
send Send a message
thread View a message thread (oldest first)

Flags:

-h, --help help for beads-mail

`beads-mail announces`

Not supported in v1

Flags:

-h, --help help for announces

`beads-mail archive`

Not supported: the beads graph is the archive

Flags:

-h, --help help for archive

`beads-mail check`

Probe for unread mail without changing anything. Exit code 0 means the probe worked, whether or not mail is waiting — branch on the output or –json, not the exit code (gt mail check exits 1 on an empty inbox; this deliberately does not, so a real failure is never mistaken for “no mail”). Nonzero exits are real errors only.

For Claude Code hooks, –inject emits the PostToolUse hook JSON envelope when mail is waiting and nothing otherwise. In-session wake-ups without polling: aw init –setup-channel.

Flags:

-h, --help help for check
--inject Output the Claude Code PostToolUse hook envelope when mail is waiting
--json Output as JSON: {"unread": N, "has_more": bool}

`beads-mail claim`

Not supported in v1: no message queues

Flags:

-h, --help help for claim

`beads-mail clear`

Not supported: server mail expires on its own

Flags:

-h, --help help for clear

`beads-mail delete`

Not supported: server mail expires on its own

Flags:

-h, --help help for delete

`beads-mail drain`

Not supported in v1

Flags:

-h, --help help for drain

`beads-mail help`

Show help for a beads-mail verb (‘bd mail’ swallows –help; this reaches us)

Flags:

-h, --help help for help

`beads-mail inbox`

List unread messages (read-only; reading is what marks read)

Flags:

-a, --all Show all messages, read and unread (gt's default view)
--cursor string Continue a previous listing from its printed cursor
-h, --help help for inbox
--json Output as JSON
-u, --unread Show only unread messages (the default)

`beads-mail mark-read`

Mark messages as read

Flags:

--all Mark all unread messages as read
-h, --help help for mark-read

`beads-mail mark-unread`

Not supported: read state cannot be cleared

Flags:

-h, --help help for mark-unread

`beads-mail peek`

Preview the first unread message without marking it read

Flags:

-h, --help help for peek

`beads-mail read`

Read one message by id, or by its number in the most recent inbox listing. Reading marks the message read (unlike gt mail read, which does not) because read state drives the wake path here; use peek or thread for a look that changes nothing.

Flags:

-h, --help help for read
--json Output as JSON (raw message, envelope included)

`beads-mail release`

Not supported in v1: no message queues

Flags:

-h, --help help for release

`beads-mail reply`

Reply to a message

Flags:

--body string Alias for --message
-h, --help help for reply
-m, --message string Reply message body
--stdin Read the reply body from stdin (delegate extension; gt reply lacks it, but shell-unsafe bodies need it)
-s, --subject string Override reply subject (default: Re: <original>)

`beads-mail search`

Not supported in v1: no server-side mail search

Flags:

-h, --help help for search

`beads-mail send`

Send mail to a beads-style name (mapped in .beads/aweb-mail.toml), an aweb address like acme.aweb.ai/reviewer, or a did:aw identity. The resolved address is always shown: mail goes out under this workspace’s cryptographically verified identity.

Flags:

--body string Alias for --message
--cc stringArray Not supported in v1: send to each recipient separately
--from string Not supported: sender identity is cryptographic here
-h, --help help for send
-m, --message string Message body
--no-notify No-op at priority <= normal (idle wake anyway); cannot silence high/urgent
-n, --notify Bump priority to high so the recipient wakes
--permanent Carry ephemeral=false metadata; v1 does not promote the underlying message bead
--pinned Carried in the beads-mail envelope; no delivery behavior
--priority int Message priority (0=urgent, 1=high, 2=normal, 3=low, 4=backlog); 0-1 wake the recipient (default 2)
--reply-to string Message ID this replies to; continues that conversation
--self Send to this workspace's own identity
--stdin Read message body from stdin
-s, --subject string Message subject (required)
--to string Recipient address (alternative to the positional argument)
--type string Message type (task, scavenge, notification, reply); carried in the beads-mail envelope (default "notification")
--urgent Set priority=0 (urgent)
--wisp Use the beads ephemeral default (default true)

`beads-mail thread`

View a message thread (oldest first)

Flags:

-h, --help help for thread
--json Output as JSON

`chat`

Real-time chat

Subcommands:

extend-wait Ask the other party to wait longer
history Show chat history with a recipient name or address
listen Wait for a message without sending
open Open a chat session
pending List pending chat sessions
read Mark chat messages read by session and message id
send Send a message to an exact chat session
send-and-leave Send a message and leave the conversation
send-and-wait Send a message and wait for a reply
show-pending Show pending messages for a recipient name or address

Flags:

-h, --help help for chat
--team string Override the selected team_id for this command

`chat extend-wait`

Ask the other party to wait longer. Warning: double-quoted shell arguments expand backticks and $(…) before aw runs; use –body-file for Markdown or command examples

Flags:

--body-file string Read message body from a file; safe for Markdown or command examples
--e2ee Send E2E encrypted wait extension; fails closed if encryption keys are missing
-h, --help help for extend-wait
--plaintext Send explicit server-readable plaintext wait extension (currently the default)

`chat history`

Show chat history with a recipient name or address

Flags:

-h, --help help for history
--limit int Maximum messages to fetch (default 1000)
--message-id string Fetch one message by id when using --session-id
--session-id string Fetch chat history by session id instead of recipient
--unread-only Fetch unread messages only

`chat listen`

Wait for a message without sending

Flags:

-h, --help help for listen
--wait int Seconds to wait for a message (0 = no wait) (default 120)

`chat open`

Open a chat session

Flags:

-h, --help help for open

`chat pending`

List pending chat sessions

Flags:

-h, --help help for pending

`chat read`

Mark chat messages read by session and message id

Flags:

-h, --help help for read
--message-id string Last delivered message id to mark read
--session-id string Chat session id

`chat send`

Send a message to an exact chat session

Flags:

--body string Body. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --body-file for Markdown or command examples
--body-file string Read message body from a file; safe for Markdown or command examples
--e2ee Send E2E encrypted chat; fails closed if encryption keys are missing
-h, --help help for send
--leave Leave the conversation after sending
--plaintext Send explicit server-readable plaintext chat (currently the default)
--session-id string Existing chat session id

`chat send-and-leave`

Send a message and leave the conversation. Warning: double-quoted shell arguments expand backticks and $(…) before aw runs; use –body-file for Markdown or command examples

Flags:

--body-file string Read message body from a file; safe for Markdown or command examples
--e2ee Send E2E encrypted chat; fails closed if encryption keys are missing
-h, --help help for send-and-leave
--plaintext Send explicit server-readable plaintext chat (currently the default)
--start-conversation Start a new conversation instead of continuing an existing one

`chat send-and-wait`

Send a message and wait for a reply. Warning: double-quoted shell arguments expand backticks and $(…) before aw runs; use –body-file for Markdown or command examples

Flags:

--body-file string Read message body from a file; safe for Markdown or command examples
--e2ee Send E2E encrypted chat; fails closed if encryption keys are missing
-h, --help help for send-and-wait
--plaintext Send explicit server-readable plaintext chat (currently the default)
--start-conversation Start conversation (5min default wait)
--wait int Seconds to wait for reply (default 120)

`chat show-pending`

Show pending messages for a recipient name or address

Flags:

-h, --help help for show-pending

`contacts`

Manage contacts

Subcommands:

add Add a contact
list List contacts
remove Remove a contact by address

Flags:

-h, --help help for contacts
--team string Override the selected team_id for this command

`contacts add`

Add a contact

Flags:

-h, --help help for add
--label string Label for the contact

`contacts list`

List contacts

Flags:

-h, --help help for list

`contacts remove`

Remove a contact by address

Flags:

-h, --help help for remove

`control`

Send control signals to agents

Subcommands:

interrupt Send interrupt signal to an agent
pause Send pause signal to an agent
resume Send resume signal to an agent

Flags:

-h, --help help for control
--team string Override the selected team_id for this command

`control interrupt`

Send interrupt signal to an agent

Flags:

--agent string Agent name to send signal to
-h, --help help for interrupt

`control pause`

Send pause signal to an agent

Flags:

--agent string Agent name to send signal to
-h, --help help for pause

`control resume`

Send resume signal to an agent

Flags:

--agent string Agent name to send signal to
-h, --help help for resume

`directory`

Search or look up global identities in the network directory

Flags:

--capability string Filter by capability
--domain string Filter by domain
-h, --help help for directory
--limit int Max results (default 100)
--query string Search handle/description
--team string Override the selected team_id for this command

`events`

Event stream operations

Subcommands:

stream Listen to real-time agent events via SSE

Flags:

-h, --help help for events
--team string Override the selected team_id for this command

`events stream`

Listen to real-time agent events via SSE

Flags:

-h, --help help for stream
--timeout int Stop after N seconds (0 = indefinite)

`gc-mail`

Mail for Gas City, across machines and organizations.

Gas City’s mail is pluggable: GC_MAIL=exec: makes gc delegate every mail operation to a command. This is that command, backed by aweb — durable delivery, recipients who can be offline, and messages signed by a cryptographically verifiable identity.

Setup, once per city:

npm i -g @awebai/aw aw init export GC_MAIL=exec:aw-gc-mail

‘aw-gc-mail’ is installed by the same npm package and runs this command. GC_MAIL names a single command with no arguments, which is why the launcher exists; ’exec:aw gc-mail’ would look for a program literally named “aw gc-mail”.

This command speaks gc’s JSON protocol on stdin/stdout. It is meant to be run by gc, not by hand — but every operation is a plain subcommand, so ‘aw gc-mail inbox’ works for a look, and ‘aw gc-mail resolve ’ shows where a recipient name would actually go.

Optional in-session wake-ups when mail arrives: aw init –setup-channel.

Subcommands:

all List all messages, read and unread, as JSON
archive Not supported: aweb mail is delivery, not storage
check List unread messages as JSON without marking anything read
count Report {“total”:N,“unread”:N} for this workspace
delete Not supported: aweb mail is delivery, not storage
ensure-running Readiness probe (no-op: gc discards this operation’s result)
get Fetch one message as JSON without marking it read
inbox List unread messages as JSON (read-only)
mark-read Mark one message read
mark-unread Not supported: read state cannot be cleared
read Fetch one message as JSON and mark it read
reply Reply into a message’s conversation (JSON on stdin, JSON message on stdout)
resolve Show the aweb address a recipient name resolves to
send Send a message (JSON on stdin, JSON message on stdout)
thread List a conversation’s messages as JSON, oldest first

Flags:

-h, --help help for gc-mail

`gc-mail all`

Lists one page of this workspace’s mail, read and unread. gc’s Provider documents this as “all open messages”; aweb has no open/closed state, so it is every message the inbox still holds within the server’s retention window.

Flags:

-h, --help help for all

`gc-mail archive`

Not supported: aweb mail is delivery, not storage

Flags:

-h, --help help for archive

`gc-mail check`

Identical to ‘inbox’ here: both are read-only unread listings. gc keeps the two operations apart because a backend’s inbox may mark messages read; this one never does.

Flags:

-h, --help help for check

`gc-mail count`

Counts this workspace’s mail. “Total” counts what the inbox holds inside the server’s retention window — aweb mail is delivery, not an archive, so it is not a cumulative all-time total. Counting stops after 4000 messages; a larger inbox reports that ceiling rather than a wrong number.

Flags:

-h, --help help for count

`gc-mail delete`

Not supported: aweb mail is delivery, not storage

Flags:

-h, --help help for delete

`gc-mail ensure-running`

gc calls this once, before the first operation of a provider instance, and throws away both its output and its exit status. There is nothing useful to report through a channel nobody reads, so this succeeds immediately. Run ‘aw doctor’ or ‘aw gc-mail inbox’ to check the setup for real.

Flags:

-h, --help help for ensure-running

`gc-mail get`

Fetches one message by id and leaves its read state alone. Visible for messages this workspace sent as well as received.

Flags:

-h, --help help for get

`gc-mail inbox`

Lists this workspace’s unread mail as a JSON array. Read-only: nothing is marked read here.

gc passes the mailbox it wants ($GC_SESSION_ID, $GC_ALIAS, $GC_AGENT, or “human”). This workspace has exactly one aweb identity, so the argument is accepted and ignored — every gc session in this city shares one inbox. That is the design record’s §5 limitation, not a bug.

Flags:

-h, --help help for inbox

`gc-mail mark-read`

Marks one message read without displaying it. Emits nothing on success; gc’s protocol expects no output from this operation.

Flags:

-h, --help help for mark-read

`gc-mail mark-unread`

Not supported: read state cannot be cleared

Flags:

-h, --help help for mark-unread

`gc-mail read`

Fetches one message by id and marks it read. Reading is what marks read here, because aweb’s read state drives the unread count and the wake path: a displayed message that stayed unread would keep re-firing.

If the acknowledgement fails, this exits nonzero rather than reporting a message as read that is not.

Flags:

-h, --help help for read

`gc-mail reply`

Reads {“from”:…,“subject”:…,“body”:…} on stdin and sends the body into the conversation that belongs to, then marks that message read. An empty subject becomes “Re: ”.

The reply goes to the conversation’s counterparty by construction; there is no recipient argument to get wrong.

Flags:

-h, --help help for reply

`gc-mail resolve`

Prints where a gc recipient name would actually deliver, without sending anything. This is the disclosure surface for the optional per-city map in .gc/aweb-mail.toml: gc’s exec protocol gives a provider no way to print a “sent to X -> Y” line during ‘gc mail send’, so the resolution is inspectable here instead.

Flags:

-h, --help help for resolve

`gc-mail send`

Reads {“from”:…,“subject”:…,“body”:…} on stdin and sends the body to under this workspace’s verified aweb identity. The “from” field is gc’s local mailbox name; it is recorded nowhere as sender identity, because sender identity here is cryptographic rather than asserted.

The message returned on stdout carries the RESOLVED aweb address in its “to” field, which is how ‘gc mail send –json’ and ‘gc mail read’ disclose where a mapped name actually delivered.

Flags:

-h, --help help for send

`gc-mail thread`

Renders one conversation as a JSON array, oldest first. The argument may be an aweb conversation id (what this provider reports as thread_id) or any message id inside it.

Flags:

-h, --help help for thread

`heartbeat`

Send an explicit presence heartbeat

Flags:

-h, --help help for heartbeat
--team string Override the selected team_id for this command

`inbound-mode`

Show or set the current agent’s inbound delivery mode

Flags:

-h, --help help for inbound-mode
--team string Override the selected team_id for this command

`log`

Show local communication log

Flags:

--channel string Filter by channel (mail, chat, dm)
--from string Filter by sender (substring match)
-h, --help help for log
--limit int Max entries to show (default 20)
--team string Override the selected team_id for this command

`mail`

Agent messaging

Subcommands:

ack Acknowledge one mail message as read
inbox List inbox messages (unread only by default)
reply Reply to an existing mail conversation
send Send a message to another agent
show Show a mail conversation or exact message

Flags:

-h, --help help for mail
--team string Override the selected team_id for this command

`mail ack`

Acknowledge one mail message as read

Flags:

-h, --help help for ack

`mail inbox`

List inbox messages, newest first and unread only by default. Messages shown by this command are acknowledged as read.

The response is one bounded page. Text output reports when more messages exist and prints a continuation command; JSON output carries has_more and next_cursor. Pass the returned value to –cursor to continue without overlap.

Flags:

--cursor string Continue from next_cursor in a previous inbox response
-h, --help help for inbox
--limit int Max messages per page (default 50)
--show-all Show all messages including already-read

`mail reply`

Reply to an existing mail conversation

Flags:

--body string Body. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --body-file for Markdown or command examples
--body-file string Read message body from a file; safe for Markdown or command examples
--e2ee Send E2E encrypted mail; fails closed if encryption keys are missing
-h, --help help for reply
--plaintext Send explicit server-readable plaintext mail (currently the default)
--priority string Priority: low|normal|high|urgent (default "normal")
--subject string Subject

`mail send`

Send a message to another agent

Flags:

--body string Body. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --body-file for Markdown or command examples
--body-file string Read message body from a file; safe for Markdown or command examples
--conversation-id string Existing mail conversation to continue
--e2ee Send E2E encrypted mail; fails closed if encryption keys are missing
-h, --help help for send
--plaintext Send explicit server-readable plaintext mail (currently the default)
--priority string Priority: low|normal|high|urgent (default "normal")
--subject string Subject
--to string Recipient name within the active team, or a routable address
--to-address string Recipient address (domain/name)
--to-did string Recipient stable identity (did:aw:...)

`mail show`

Show mail by conversation or exact message ID.

With –message-id, one unique message is selected. The conversation-window direction and 500-message ceiling below do not apply.

With –conversation-id, –limit caps how many messages are returned and defaults to 200. The messages returned are the OLDEST ones, so on a conversation longer than the limit the newest messages are the ones missing - which is the opposite of what someone checking for recent mail expects.

aw mail inbox windows from the other end and has a different default and ceiling. Do not carry an expectation from one command to the other.

To read a whole conversation, pass –limit above its length and check the returned count. If it equals the limit, there may be more; raise it and re-run, up to 500. At the 500-message ceiling, an exact full window cannot establish completeness. The conversation endpoint rejects higher limits and has no paging flag, so a conversation longer than 500 messages cannot be returned whole by this command.

Flags:

--conversation-id string Mail conversation to inspect
-h, --help help for show
--limit int For --conversation-id, max messages from the OLDEST end; exact --message-id reads are not windowed (default 200)
--message-id string Legacy mail message to inspect

`wake`

Terminal wake broker.

One daemon per host holds a reconnecting event stream per registered identity, coalesces the resulting hints per instance, and types a short fetch instruction plus a hint summary into each instance’s original terminal through OATS.

It never fetches, decrypts or types a sender’s message, and it never acknowledges anything: the instance’s own aw does all of that.

Subcommands:

deregister Remove an instance home from the wake broker
pause Stop the broker typing into one instance, durably
register Register an instance home with the wake broker
resume Let the broker type into one instance again
run Run the host wake broker in the foreground
status Report per-home broker state, last attempt, and pending hints

Flags:

-h, --help help for wake

`wake deregister`

Remove an instance home from the wake broker.

Called by the OATS retire hook after quiescence. The broker never stops an instance and never removes a registration on its own; an instance it observed stopped is marked inactive and waits here.

An unknown or already-retired home exits 0 with a note: the hook may run twice, or after the pending expiry already dropped the registration, and neither is a failed retirement.

Flags:

-h, --help help for deregister
--home string Absolute instance home path
--state-dir string Broker state directory (default $AW_WAKE_STATE_DIR, else ~/.config/aw/wake)

`wake pause`

Stop the broker typing into one instance.

Pause is durable broker state and survives a restart. It suppresses typing; it does not stop the stream, drop hints, or acknowledge anything.

Flags:

-h, --help help for pause
--home string Absolute instance home path
--state-dir string Broker state directory (default $AW_WAKE_STATE_DIR, else ~/.config/aw/wake)

`wake register`

Called by the OATS spawn hook. –delivery must be session: the broker and a live native channel are two presentation surfaces on one identity, and running both doubles every wake. A registration stays pending until an inspect reports the instance present; pending errors are tolerated until the 30-minute expiry.

Exit 0 means the registration was written durably: over the daemon’s socket when it is up, and straight to the state directory when it is not, so a hook never fails because the broker is restarting. A non-zero exit means refused — a missing –delivery session, a relative path, or an unreadable identity home.

–identity-home here names the instance’s own identity home, and shadows the root flag of the same name for this command. Give the principal’s home before the subcommand (aw –identity-home wake register …) when you need both.

Flags:

--backend string Terminal backend hint: tmux or herdr
--delivery string Delivery mode recorded by the spawn hook; legacy/external uses session, native mixed uses native-channel or native-pi
-h, --help help for register
--home string Absolute instance home path
--identity-home string Absolute identity home the instance streams under (legacy single-identity registration)
--primary-identity-home string Absolute native primary identity home for disjoint native-channel/native-pi registrations
--receive-identity-json stringArray JSON receive identity binding; repeat for multi-identity broker receive
--registration-json string Read the complete wake registration JSON from this file, or '-' for stdin
--runtime-delivery string Explicit runtime delivery owner: external-session, native-channel, or native-pi
--state-dir string Broker state directory (default $AW_WAKE_STATE_DIR, else ~/.config/aw/wake)

`wake resume`

Let the broker type into one instance again

Flags:

-h, --help help for resume
--home string Absolute instance home path
--state-dir string Broker state directory (default $AW_WAKE_STATE_DIR, else ~/.config/aw/wake)

`wake run`

Run the host wake broker in the foreground.

One daemon per host. All state is on disk and there is no cursor, so the daemon is safe to restart at any time: it re-reads its registrations and pending hints, and the reconnect snapshot re-raises anything still unread. A second start exits 0 reporting the running daemon.

Flags:

--coalesce int Coalescing window in milliseconds (default 2000)
-h, --help help for run
--max-streams int Maximum concurrent identity event streams (default 128)
--oats-bin oats OATS executable to run (default $AW_WAKE_OATS_BIN, else oats from PATH)
--rate-limit int Minimum milliseconds between submission attempts per instance (default 30000)
--state-dir string Broker state directory (default $AW_WAKE_STATE_DIR, else ~/.config/aw/wake)

`wake status`

Report per-home broker state, last attempt, and pending hints

Flags:

-h, --help help for status
--max-streams int Stream bound reported when the daemon is down (default 128)
--state-dir string Broker state directory (default $AW_WAKE_STATE_DIR, else ~/.config/aw/wake)

`agent`

Inspect local materialized agent homes under agents/instances/.

Subcommands:

profile Inspect the Library profile recorded in a local agent home

Flags:

-h, --help help for agent

`agent profile`

Inspect the Library profile recorded in a local agent home

Subcommands:

show Show the recorded profile ref/snapshot (.aw/profile/ref.json) for a materialized agent

Flags:

-h, --help help for profile

`agent profile show`

Show the Library profile a local agent home was materialized from - the blueprint and profile refs, versions, and content digests recorded in .aw/profile/ref.json. This is what aw team admin refresh updates and what the materialize seam records; it never asks a remote service which profile is in use.

Flags:

-h, --help help for show
--home string Agent home directory override (default: agents/instances/<name>)

`instructions`

Read and manage shared team instructions

Subcommands:

activate Activate an existing shared team instructions version
history List shared team instructions history
inject Inject current team instructions into agent docs
reset Reset shared team instructions to the server default
set Create and activate a new shared team instructions version
show Show shared team instructions

Flags:

-h, --help help for instructions
--team string Override the selected team_id for this command

`instructions activate`

Activate an existing shared team instructions version

Flags:

-h, --help help for activate

`instructions history`

List shared team instructions history

Flags:

-h, --help help for history
--limit int Max instruction versions (default 20)

`instructions inject`

Fetch the active team instructions through the current workspace and replace the target’s marker-delimited block. The exact target defaults to the current directory. This explicit operation also adds the block when the target is not yet marked.

Flags:

-h, --help help for inject

`instructions reset`

Reset shared team instructions to the server default

Flags:

-h, --help help for reset

`instructions set`

Create and activate a new shared team instructions version

Flags:

--body string Instructions Markdown body. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --body-file for Markdown or command examples
--body-file string Read instructions Markdown from a file ('-' for stdin); safe for Markdown or command examples
-h, --help help for set

`instructions show`

Show shared team instructions

Flags:

-h, --help help for show

`lock`

Distributed locks

Subcommands:

acquire Acquire a lock
list List active locks
release Release a lock
renew Renew a lock
revoke Revoke locks

Flags:

-h, --help help for lock
--team string Override the selected team_id for this command

`lock acquire`

Acquire a lock

Flags:

-h, --help help for acquire
--resource-key string Opaque resource key
--ttl-seconds int TTL seconds (default 3600)

`lock list`

List active locks

Flags:

-h, --help help for list
--mine Show only locks held by the current workspace name
--prefix string Prefix filter

`lock release`

Release a lock

Flags:

-h, --help help for release
--resource-key string Opaque resource key

`lock renew`

Renew a lock

Flags:

-h, --help help for renew
--resource-key string Opaque resource key
--ttl-seconds int TTL seconds (default 3600)

`lock revoke`

Revoke locks

Flags:

-h, --help help for revoke
--prefix string Optional prefix filter

`notify`

Check for pending chat notifications.

Silent if no pending chats; outputs JSON with additionalContext if there are messages waiting. Designed for Claude Code PostToolUse hooks so notifications are surfaced to the agent automatically.

Hook configuration in .claude/settings.json (set up via aw init –setup-hooks): “hooks”: { “PostToolUse”: [{ “matcher”: “.*”, “hooks”: [{“type”: “command”, “command”: “aw notify”}] }] }

Flags:

-h, --help help for notify
--team string Override the selected team_id for this command

`role-name`

The role name is this workspace’s operating responsibility on this team. It is initialized from the materialized profile during setup, but remains independently mutable. Changing it does not change which profile the workspace runs or grant additional authority.

Subcommands:

set Set the current workspace operating role

Flags:

-h, --help help for role-name
--team string Override the selected team_id for this command

`role-name set`

Set the current workspace operating role.

Flags:

-h, --help help for set

`roles`

Read and manage team roles bundles and role definitions

Subcommands:

activate Activate an existing team roles bundle version
add Add or update one role in the active team roles bundle
deactivate Deactivate team roles by replacing the active bundle with an empty bundle
history List team roles history
list List roles defined in the active team roles bundle
reset Reset team roles to the server default bundle
set Create and activate a new team roles bundle version
show Show role guidance from the active team roles bundle

Flags:

-h, --help help for roles
--team string Override the selected team_id for this command

`roles activate`

Activate an existing team roles bundle version

Flags:

-h, --help help for activate

`roles add`

Add or update one role in the active team roles bundle.

This is the novice-friendly way to build a roles bundle from resource-pack role Markdown files one role at a time. It reads the active bundle, adds the role, creates a new bundle version, and activates it.

Flags:

-h, --help help for add
--playbook string Role playbook Markdown body. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --playbook-file for Markdown or command examples
--playbook-file string Read role playbook Markdown from a file ('-' for stdin); safe for Markdown or command examples
--replace Replace an existing role with the same name
--title string Human-readable role title (defaults to role name)

`roles deactivate`

Deactivate team roles by replacing the active bundle with an empty bundle

Flags:

-h, --help help for deactivate

`roles history`

List team roles history

Flags:

-h, --help help for history
--limit int Max role bundle versions (default 20)

`roles list`

List roles defined in the active team roles bundle

Flags:

-h, --help help for list

`roles reset`

Reset team roles to the server default bundle

Flags:

-h, --help help for reset

`roles set`

Create and activate a new team roles bundle version

Flags:

--bundle-file string Read team roles bundle JSON from a file ('-' for stdin); safe for Markdown playbooks or command examples
--bundle-json string Team roles bundle JSON. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --bundle-file for Markdown or command examples
-h, --help help for set

`roles show`

Show role guidance from the active team roles bundle

Flags:

--all-roles Include all role playbooks instead of only the selected role
-h, --help help for show
--role string Compatibility alias for --role-name
--role-name string Preview a specific role name

`run`

Start the requested AI coding agent in this directory.

In a TTY, if this directory is not initialized yet, aw run can guide you through supported onboarding before starting the provider. The explicit bootstrap path is aw init, backed by guided onboarding, hosted signup, or a team certificate already present in .aw/.

Current implementation includes:

repeated provider invocations (currently Claude and Codex)
provider session continuity when –continue is requested
/stop, /wait, /autofeed on|off, /quit, and prompt override controls
aw event-stream wakeups for mail, chat, and optional work events
optional background services declared in aw run config

This aw-first command intentionally excludes bead-specific dispatch.

Flags:

--allowed-tools string Provider-specific allowed tools string
--autofeed-work Wake for work-related events in addition to incoming mail/chat
--base-prompt string Override the configured base mission prompt for this run
--comms-prompt-suffix string Override the configured comms cycle prompt suffix for this run
--continue Continue the most recent provider session across runs
--dir string Working directory for the agent process
-h, --help help for run
--idle-wait int Reserved idle-wait setting for future dispatch modes (default 30)
--init Prompt for ~/.config/aw/run.json values and write them
--max-runs int Stop after N runs (0 means infinite)
--model string Provider-specific model override
--prompt string Initial prompt for the first provider run
--provider-pty Run the provider subprocess inside a pseudo-terminal instead of plain pipes when interactive controls are available
--team string Override the selected team_id for this command
--trip-on-danger Remove provider bypass flags and use native provider safety checks
--wait int Idle seconds per wake-stream wait cycle (default 20)
--work-prompt-suffix string Override the configured work cycle prompt suffix for this run

`task`

Manage tasks

Subcommands:

close Close one or more tasks
comment Manage task comments
create Create a new task
delete Delete a task
dep Manage task dependencies
list List tasks
reopen Reopen a closed task
show Show task details
stats Show task statistics
update Update a task

Flags:

-h, --help help for task
--team string Override the selected team_id for this command

`task close`

Close one or more tasks

Flags:

-h, --help help for close
--reason string Reason for closing (replaces notes). Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --reason-file for Markdown or command examples
--reason-file string Read closing reason from a file; safe for Markdown or command examples

`task comment`

Manage task comments

Subcommands:

add Add a comment to a task
list List comments on a task

Flags:

-h, --help help for comment

`task comment add`

Add a comment to a task. Warning: double-quoted shell arguments expand backticks and $(…) before aw runs; use –body-file for Markdown or command examples

Flags:

--body string Comment body. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --body-file for Markdown or command examples
--body-file string Read comment body from a file; safe for Markdown or command examples
-h, --help help for add

`task comment list`

List comments on a task

Flags:

-h, --help help for list

`task create`

Create a new task

Flags:

--assignee string Assignee agent name
--description string Task description. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --description-file for Markdown or command examples
--description-file string Read task description from a file; safe for Markdown or command examples
-h, --help help for create
--labels string Comma-separated labels
--notes string Task notes. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --notes-file for Markdown or command examples
--notes-file string Read task notes from a file; safe for Markdown or command examples
--parent string Parent task ref
--priority string Priority 0-4 (accepts P0-P4)
--title string Task title (required)
--type string Task type (task, bug, feature, epic)

`task delete`

Delete a task

Flags:

-h, --help help for delete

`task dep`

Manage task dependencies

Subcommands:

add Add a dependency
list List dependencies for a task
remove Remove a dependency

Flags:

-h, --help help for dep

`task dep add`

Add a dependency

Flags:

-h, --help help for add

`task dep list`

List dependencies for a task

Flags:

-h, --help help for list

`task dep remove`

Remove a dependency

Flags:

-h, --help help for remove

`task list`

List tasks

Flags:

--assignee string Filter by assignee agent name
-h, --help help for list
--labels string Filter by labels (comma-separated)
--parent string Filter by parent task ref
--priority string Filter by priority 0-4 (accepts P0-P4)
--status string Filter by status (open, in_progress, closed, blocked)
--type string Filter by type (task, bug, feature, epic)

`task reopen`

Reopen a closed task

Flags:

-h, --help help for reopen

`task show`

Show task details

Flags:

-h, --help help for show

`task stats`

Show task statistics

Flags:

-h, --help help for stats

`task update`

Update a task

Flags:

--assignee string Assignee agent name (empty to unassign)
--description string Description. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --description-file for Markdown or command examples
--description-file string Read task description from a file; safe for Markdown or command examples
-h, --help help for update
--labels string Comma-separated labels
--notes string Notes. Warning: double-quoted shell arguments expand backticks and $(...) before aw runs; use --notes-file for Markdown or command examples
--notes-file string Read task notes from a file; safe for Markdown or command examples
--parent string Parent task ref (empty to make root)
--priority string Priority 0-4 (accepts P0-P4)
--status string Status (open, in_progress, closed)
--title string Title
--type string Type (task, bug, feature, epic)

`work`

Discover coordination-aware work

Subcommands:

active List active in-progress work across the team
blocked List blocked tasks
ready List ready tasks that are not already claimed by other workspaces

Flags:

-h, --help help for work
--team string Override the selected team_id for this command

`work active`

List active in-progress work across the team

Flags:

-h, --help help for active

`work blocked`

List blocked tasks

Flags:

-h, --help help for blocked

`work ready`

List ready tasks that are not already claimed by other workspaces

Flags:

-h, --help help for ready

`completion`

Generate the autocompletion script for aw for the specified shell. See each sub-command’s help for details on how to use the generated script.

Subcommands:

bash Generate the autocompletion script for bash
fish Generate the autocompletion script for fish
powershell Generate the autocompletion script for powershell
zsh Generate the autocompletion script for zsh

Flags:

-h, --help help for completion

`completion bash`

Generate the autocompletion script for the bash shell.

This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager.

To load completions in your current shell session:

source <(aw completion bash)

To load completions for every new session, execute once:

Linux:

aw completion bash > /etc/bash_completion.d/aw

macOS:

aw completion bash > $(brew --prefix)/etc/bash_completion.d/aw

You will need to start a new shell for this setup to take effect.

Flags:

-h, --help help for bash
--no-descriptions disable completion descriptions

`completion fish`

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

aw completion fish | source

To load completions for every new session, execute once:

aw completion fish > ~/.config/fish/completions/aw.fish

You will need to start a new shell for this setup to take effect.

Flags:

-h, --help help for fish
--no-descriptions disable completion descriptions

`completion powershell`

Generate the autocompletion script for powershell.

To load completions in your current shell session:

aw completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

Flags:

-h, --help help for powershell
--no-descriptions disable completion descriptions

`completion zsh`

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(aw completion zsh)

To load completions for every new session, execute once:

Linux:

aw completion zsh > "${fpath[1]}/_aw"

macOS:

aw completion zsh > $(brew --prefix)/share/zsh/site-functions/_aw

You will need to start a new shell for this setup to take effect.

Flags:

-h, --help help for zsh
--no-descriptions disable completion descriptions

`doctor`

Diagnose local identity, workspace, and coordination state

Subcommands:

identity Run identity doctor checks
local Run local doctor checks
messaging Run messaging doctor checks
registry Run registry doctor checks
support-bundle Write a redacted doctor support bundle
team Run team doctor checks
workspace Run workspace doctor checks

Flags:

--dry-run Plan fixes without applying them
--fix Apply safe doctor fixes
-h, --help help for doctor
--offline Run without network checks
--online Allow online checks
--team string Override the selected team_id for this command
--verbose Include verbose diagnostic details

`doctor identity`

Run identity doctor checks

Flags:

-h, --help help for identity

`doctor local`

Run local doctor checks

Flags:

-h, --help help for local

`doctor messaging`

Run messaging doctor checks

Flags:

-h, --help help for messaging

`doctor registry`

Run registry doctor checks

Flags:

-h, --help help for registry

`doctor support-bundle`

Write a redacted doctor support bundle

Flags:

-h, --help help for support-bundle
--output string Output JSON file

`doctor team`

Run team doctor checks

Flags:

-h, --help help for team

`doctor workspace`

Run workspace doctor checks

Flags:

-h, --help help for workspace

`help`

Help provides help for any command in the application. Simply type aw help [path to command] for full details.

Flags:

-h, --help help for help

`plugin`

Manage aw plugins

Subcommands:

install Install a plugin into the trusted aw plugin directory
list List installed plugins
remove Remove an installed plugin
reserved-names Emit reserved top-level aw app ids
update Update an installed manifest plugin

Flags:

-h, --help help for plugin

`plugin install`

Install a plugin into the trusted aw plugin directory

Flags:

--app-id string App id to record in plugin provenance
--app-version string App version to record in plugin provenance
--dev-origin string Override the app origin to this base URL for a self-hosted or dev service; the request base URL becomes this, bypassing the manifest origin self-consistency check
-h, --help help for install
--manifest-version string Manifest version to record in plugin provenance
--origin string App origin to record in plugin provenance

`plugin list`

List installed plugins

Flags:

-h, --help help for list

`plugin remove`

Remove an installed plugin

Flags:

-h, --help help for remove

`plugin reserved-names`

Emit reserved top-level aw app ids

Flags:

-h, --help help for reserved-names

`plugin update`

Update an installed manifest plugin

Flags:

-h, --help help for update

`upgrade`

Upgrade aw to the latest version

Flags:

-h, --help help for upgrade

`version`

Print version information

Flags:

-h, --help help for version

`blueprint`

Inspect and manage Library blueprints

Subcommands:

inspect Inspect a blueprint without importing or materializing it
materialize Materialize one local blueprint profile into a local agent home
publish-profile Publish one local blueprint profile to the team’s private Library shelf

Flags:

-h, --help help for blueprint

`blueprint inspect`

Inspect a blueprint without importing or materializing it

Flags:

-h, --help help for inspect
--json Print machine-readable JSON

`blueprint materialize`

Materialize one local blueprint profile into a local agent home

Flags:

--force Overwrite existing materialized files
-h, --help help for materialize
--json Print machine-readable JSON
--profile string Profile id to materialize
--target string Target local agent home directory

`blueprint publish-profile`

Pack a profile from a local blueprint source and publish it to the team’s private Library shelf (create-shelf-profile). –profile is optional when the source has exactly one profile and required when it has more than one. The request is signed with the active team certificate (library:write).

Flags:

-h, --help help for publish-profile
--json Print machine-readable JSON
--profile string Profile id to publish (optional when the source has exactly one)
--tag strings Tag to attach to the shelf profile (repeatable)

`session`

Session-scoped coordination

Subcommands:

lease Manage the principal’s session admission lease

Flags:

-h, --help help for session

`session lease`

Manage the principal’s session admission lease

Subcommands:

acquire
release
renew
status
takeover Explicit audited early takeover

Flags:

-h, --help help for lease

`session lease acquire`

Flags:

-h, --help help for acquire
--session-id string Per-session identifier
--session-key string Per-session secret (at least 32 characters; avoid shell history)
--ttl-seconds int Lease TTL in seconds (default 300)

`session lease release`

Flags:

-h, --help help for release
--session-id string Per-session identifier
--session-key string Per-session secret (at least 32 characters; avoid shell history)

`session lease renew`

Flags:

-h, --help help for renew
--session-id string Per-session identifier
--session-key string Per-session secret (at least 32 characters; avoid shell history)
--ttl-seconds int Lease TTL in seconds (default 300)

`session lease status`

Flags:

-h, --help help for status

`session lease takeover`

Explicit audited early takeover

Flags:

-h, --help help for takeover
--reason string Required audited reason
--session-id string Per-session identifier
--session-key string Per-session secret (at least 32 characters; avoid shell history)
--ttl-seconds int Lease TTL in seconds (default 300)