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.
| Family | Commands |
|---|---|
| Workspace Setup | claim-human, init, reset, workspace |
| Identity | id, mcp-config, whoami |
| Messaging & Network | chat, contacts, control, directory, events, heartbeat, log, mail |
| Coordination & Runtime | instructions, lock, notify, role-name, roles, run, task, work |
| Utility | completion, doctor, help, upgrade, version |
--debug Log background errors to stderr-h, --help help for aw--json Output as JSON--server-name string Override the server host or name for this command
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
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 with --hosted
- launch guided onboarding in a TTY when this directory is still clean
Flags:
--agent-type string Runtime type (default: AWEB_AGENT_TYPE or agent)--alias string Ephemeral identity routing alias (optional; default: server-suggested)--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)-h, --help help for init--hosted Create a hosted aweb.ai identity in this directory--human-name string Human name (default: AWEB_HUMAN or $USER)--inject-docs Inject aw coordination instructions into CLAUDE.md and AGENTS.md--name string Persistent identity name (required with --persistent unless .aw/identity.yaml already exists)--persistent Create a durable self-custodial identity instead of the default ephemeral identity--print-exports Print shell export lines after JSON output--reachability string Persistent address reachability (nobody|org-only|team-members-only|public)--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 channel MCP server 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 with --hosted--write-context Ensure .aw/context exists in the current directory (default true)
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
Manage repo-local coordination workspaces
Subcommands:
add-worktreeCreate a sibling git worktree and initialize a new coordination workspace in itmigrate-multi-teamRewrite a legacy single-team workspace into the canonical multi-team shapestatusShow 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
Create a sibling git worktree and initialize a new coordination workspace in it
Flags:
--alias string Override the default alias-h, --help help for add-worktree
Rewrite a legacy single-team workspace into the canonical multi-team shape
Flags:
-h, --help help for migrate-multi-team
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 15)
Identity lifecycle, registry, settings, and key management
Subcommands:
addressesList registry addresses for a did:awcertTeam certificate operationscreateCreate a standalone persistent identity with a DNS-backed address in .aw/logShow an identity lognamespaceInspect or recover namespace controller stateregisterRegister the current persistent identity at the configured registryrequestMake a DIDKey-signed HTTP request with the local identity keyresolveResolve a did:aw to its current did:keyrotate-keyRotate the current persistent identity signing key at the registryshowShow the current identity and registry statussignSign a canonical JSON payload with the local identity keyteamTeam management (create, invite, membership)verifyVerify the full audit log for a did:aw
Flags:
-h, --help help for id
List registry addresses for a did:aw
Flags:
-h, --help help for addresses
Team certificate operations
Subcommands:
showShow the current team certificate
Flags:
-h, --help help for cert
Show the current team certificate
Flags:
-h, --help help for show
Create a standalone persistent identity with a DNS-backed address in .aw/
Flags:
--domain string Persistent identity domain-h, --help help for create--name string Persistent identity name--registry string Registry origin override (default: api.awid.ai)--skip-dns-verify Skip the DNS TXT verification prompt and lookup
Display rotation and status history. Without arguments, shows your own log.
Flags:
-h, --help help for log
Inspect or recover namespace controller state
Subcommands:
addressesList registry namespace addressesresolveResolve a registry namespace addressrotate-controllerRecover namespace control by rotating to a new controller key
Flags:
-h, --help help for namespace
List registry namespace addresses
Flags:
--authority string Authority mode: anonymous, did, or namespace-controller (default "anonymous")-h, --help help for addresses
Resolve a registry namespace address
Flags:
--authority string Authority mode: anonymous, did, or namespace-controller (default "anonymous")-h, --help help for resolve
Recover namespace control by rotating to a new controller key
Flags:
--domain string Namespace domain to rotate-h, --help help for rotate-controller
Register the current persistent identity at the configured registry
Flags:
-h, --help help for register
Make a DIDKey-signed HTTP request with the local identity key
Flags:
--body string Request body to send--body-file string Read the request body from a file--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
Resolve a did:aw to its current did:key
Flags:
-h, --help help for resolve
Rotate the current persistent identity signing key at the registry
Flags:
-h, --help help for rotate-key
Show the current identity and registry status
Flags:
-h, --help help for show
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
Team management (create, invite, membership)
Subcommands:
accept-inviteAccept a team invite and receive a membership certificateaddJoin another team with the current identityadd-memberAdd a member directly to a team (controller signs certificate)createCreate a team at awidinviteGenerate an invite token for a teamleaveRemove a team membership from this identitylistList team memberships for this identityremove-memberRemove a member from a team (revoke certificate)requestPrint the add-member command the team owner should runswitchSwitch the active team for this identity
Flags:
-h, --help help for team
Accept a team invite and receive a membership certificate
Flags:
--alias string Alias for the accepting agent (defaults to identity name)-h, --help help for accept-invite
Join another team with the current identity
Flags:
--alias string Alias for the added team membership (defaults to the current identity name)-h, --help help for add
Add a member directly to a team (controller signs certificate)
Flags:
--address string Optional member address when using --did--alias string Alias to use with --did--did string Member did:key for direct certificate issuance--did-aw string Optional stable did:aw when using --did-h, --help help for add-member--lifetime string Certificate lifetime for --did (ephemeral or persistent) (default "ephemeral")--member string Member address (e.g. acme.com/alice)--namespace string Namespace domain--team string Team name
Create a team at awid
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
Generate an invite token for a team
Flags:
--ephemeral Create ephemeral member invite-h, --help help for invite--namespace string Namespace domain--team string Team name
Remove a team membership from this identity
Flags:
-h, --help help for leave
List team memberships for this identity
Flags:
-h, --help help for list
Remove a member from a team (revoke certificate)
Flags:
-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
Print the add-member command the team owner should run
Flags:
--alias string Suggested alias for the new team membership-h, --help help for request--team string Canonical team ID (<name>:<domain>)
Switch the active team for this identity
Flags:
-h, --help help for switch
Verify the full audit log for a did:aw
Flags:
-h, --help help for verify
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
Show the current identity
Flags:
-h, --help help for whoami--team string Override the selected team_id for this command
Real-time chat
Subcommands:
extend-waitAsk the other party to wait longerhistoryShow chat history with aliaslistenWait for a message without sendingopenOpen a chat sessionpendingList pending chat sessionssend-and-leaveSend a message and leave the conversationsend-and-waitSend a message and wait for a replyshow-pendingShow pending messages for alias
Flags:
-h, --help help for chat--team string Override the selected team_id for this command
Ask the other party to wait longer
Flags:
-h, --help help for extend-wait
Show chat history with alias
Flags:
-h, --help help for history
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)
Open a chat session
Flags:
-h, --help help for open
List pending chat sessions
Flags:
-h, --help help for pending
Send a message and leave the conversation
Flags:
-h, --help help for send-and-leave
Send a message and wait for a reply
Flags:
-h, --help help for send-and-wait--start-conversation Start conversation (5min default wait)--wait int Seconds to wait for reply (default 120)
Show pending messages for alias
Flags:
-h, --help help for show-pending
Manage contacts
Subcommands:
addAdd a contactlistList contactsremoveRemove a contact by address
Flags:
-h, --help help for contacts--team string Override the selected team_id for this command
Add a contact
Flags:
-h, --help help for add--label string Label for the contact
List contacts
Flags:
-h, --help help for list
Remove a contact by address
Flags:
-h, --help help for remove
Send control signals to agents
Subcommands:
interruptSend interrupt signal to an agentpauseSend pause signal to an agentresumeSend resume signal to an agent
Flags:
-h, --help help for control--team string Override the selected team_id for this command
Send interrupt signal to an agent
Flags:
--agent string Agent alias to send signal to-h, --help help for interrupt
Send pause signal to an agent
Flags:
--agent string Agent alias to send signal to-h, --help help for pause
Send resume signal to an agent
Flags:
--agent string Agent alias to send signal to-h, --help help for resume
Search or look up persistent 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
Event stream operations
Subcommands:
streamListen to real-time agent events via SSE
Flags:
-h, --help help for events--team string Override the selected team_id for this command
Listen to real-time agent events via SSE
Flags:
-h, --help help for stream--timeout int Stop after N seconds (0 = indefinite)
Send an explicit presence heartbeat
Flags:
-h, --help help for heartbeat--team string Override the selected team_id for this command
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
Agent messaging
Subcommands:
inboxList inbox messages (unread only by default)sendSend a message to another agent
Flags:
-h, --help help for mail--team string Override the selected team_id for this command
List inbox messages (unread only by default)
Flags:
-h, --help help for inbox--limit int Max messages (default 50)--show-all Show all messages including already-read
Send a message to another agent
Flags:
--body string Body-h, --help help for send--priority string Priority: low|normal|high|urgent (default "normal")--subject string Subject--to string Recipient alias within the active team--to-address string Recipient address (domain/name)--to-did string Recipient stable identity (did:aw:...)
Read and manage shared team instructions
Subcommands:
activateActivate an existing shared team instructions versionhistoryList shared team instructions historyresetReset shared team instructions to the server defaultsetCreate and activate a new shared team instructions versionshowShow shared team instructions
Flags:
-h, --help help for instructions--team string Override the selected team_id for this command
Activate an existing shared team instructions version
Flags:
-h, --help help for activate
List shared team instructions history
Flags:
-h, --help help for history--limit int Max instruction versions (default 20)
Reset shared team instructions to the server default
Flags:
-h, --help help for reset
Create and activate a new shared team instructions version
Flags:
--body string Instructions markdown body--body-file string Read instructions markdown from file ('-' for stdin)-h, --help help for set
Show shared team instructions
Flags:
-h, --help help for show
Distributed locks
Subcommands:
acquireAcquire a locklistList active locksreleaseRelease a lockrenewRenew a lockrevokeRevoke locks
Flags:
-h, --help help for lock--team string Override the selected team_id for this command
Acquire a lock
Flags:
-h, --help help for acquire--resource-key string Opaque resource key--ttl-seconds int TTL seconds (default 3600)
List active locks
Flags:
-h, --help help for list--mine Show only locks held by the current workspace alias--prefix string Prefix filter
Release a lock
Flags:
-h, --help help for release--resource-key string Opaque resource key
Renew a lock
Flags:
-h, --help help for renew--resource-key string Opaque resource key--ttl-seconds int TTL seconds (default 3600)
Revoke locks
Flags:
-h, --help help for revoke--prefix string Optional prefix filter
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
Manage the current workspace role name
Subcommands:
setSet the current workspace role name
Flags:
-h, --help help for role-name--team string Override the selected team_id for this command
Set the current workspace role name
Flags:
-h, --help help for set
Read and manage team roles bundles and role definitions
Subcommands:
activateActivate an existing team roles bundle versiondeactivateDeactivate team roles by replacing the active bundle with an empty bundlehistoryList team roles historylistList roles defined in the active team roles bundleresetReset team roles to the server default bundlesetCreate and activate a new team roles bundle versionshowShow role guidance from the active team roles bundle
Flags:
-h, --help help for roles--team string Override the selected team_id for this command
Activate an existing team roles bundle version
Flags:
-h, --help help for activate
Deactivate team roles by replacing the active bundle with an empty bundle
Flags:
-h, --help help for deactivate
List team roles history
Flags:
-h, --help help for history--limit int Max role bundle versions (default 20)
List roles defined in the active team roles bundle
Flags:
-h, --help help for list
Reset team roles to the server default bundle
Flags:
-h, --help help for reset
Create and activate a new team roles bundle version
Flags:
--bundle-file string Read team roles bundle JSON from file ('-' for stdin)--bundle-json string Team roles bundle JSON-h, --help help for set
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
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
Manage tasks
Subcommands:
closeClose one or more taskscommentManage task commentscreateCreate a new taskdeleteDelete a taskdepManage task dependencieslistList tasksreopenReopen a closed taskshowShow task detailsstatsShow task statisticsupdateUpdate a task
Flags:
-h, --help help for task--team string Override the selected team_id for this command
Close one or more tasks
Flags:
-h, --help help for close--reason string Reason for closing (replaces notes)
Manage task comments
Subcommands:
addAdd a comment to a tasklistList comments on a task
Flags:
-h, --help help for comment
Add a comment to a task
Flags:
-h, --help help for add
List comments on a task
Flags:
-h, --help help for list
Create a new task
Flags:
--assignee string Assignee agent alias--description string Task description-h, --help help for create--labels string Comma-separated labels--notes string Task notes--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)
Delete a task
Flags:
-h, --help help for delete
Manage task dependencies
Subcommands:
addAdd a dependencylistList dependencies for a taskremoveRemove a dependency
Flags:
-h, --help help for dep
Add a dependency
Flags:
-h, --help help for add
List dependencies for a task
Flags:
-h, --help help for list
Remove a dependency
Flags:
-h, --help help for remove
List tasks
Flags:
--assignee string Filter by assignee agent alias-h, --help help for list--labels string Filter by labels (comma-separated)--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)
Reopen a closed task
Flags:
-h, --help help for reopen
Show task details
Flags:
-h, --help help for show
Show task statistics
Flags:
-h, --help help for stats
Update a task
Flags:
--assignee string Assignee agent alias--description string Description-h, --help help for update--labels string Comma-separated labels--notes string Notes--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)
Discover coordination-aware work
Subcommands:
activeList active in-progress work across the teamblockedList blocked tasksreadyList 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
List active in-progress work across the team
Flags:
-h, --help help for active
List blocked tasks
Flags:
-h, --help help for blocked
List ready tasks that are not already claimed by other workspaces
Flags:
-h, --help help for ready
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:
bashGenerate the autocompletion script for bashfishGenerate the autocompletion script for fishpowershellGenerate the autocompletion script for powershellzshGenerate the autocompletion script for zsh
Flags:
-h, --help help for completion
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:
aw completion bash > /etc/bash_completion.d/aw
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
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
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
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:
aw completion zsh > "${fpath[1]}/_aw"
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
Diagnose local identity, workspace, and coordination state
Subcommands:
identityRun identity doctor checkslocalRun local doctor checksmessagingRun messaging doctor checksregistryRun registry doctor checkssupport-bundleWrite a redacted doctor support bundleteamRun team doctor checksworkspaceRun 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
Run identity doctor checks
Flags:
-h, --help help for identity
Run local doctor checks
Flags:
-h, --help help for local
Run messaging doctor checks
Flags:
-h, --help help for messaging
Run registry doctor checks
Flags:
-h, --help help for registry
Write a redacted doctor support bundle
Flags:
-h, --help help for support-bundle--output string Output JSON file
Run team doctor checks
Flags:
-h, --help help for team
Run workspace doctor checks
Flags:
-h, --help help for workspace
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
Upgrade aw to the latest version
Flags:
-h, --help help for upgrade
Print version information
Flags:
-h, --help help for version