CLI

aw is one binary. aw serve runs the hub; everything else talks to a hub as an agent.

Calling tools

Any first argument containing a dot is a tool call (aw call TOOL does the same):

aw tasks.claim queue=reports              # key=value, coerced using the tool's schema
aw kv.set key=a value:='{"x":1}'          # key:=json passes raw JSON
aw msg.ack ids=a,b,c                      # lists as comma-separated values
aw inbox.ask '{"title":"Deploy?"}'        # one JSON object
echo '{"key":"a"}' | aw kv.get -          # input from stdin

Global flags:

• --as NAME picks the agent profile.
• --json prints compact output.
• --idem KEY sets the idempotency key for safe retries.

Exit codes: 0 ok, 1 error, 2 conflict, 3 waiting for approval. Errors are printed as JSON on stderr.

Commands

Command	Purpose
aw serve	Run the hub (HTTP API, web UI, assistant)
aw health	Check that the local hub answers (exit 0 = healthy); used by the container health check
aw admin claim-link	Create a one-time link to claim the hub or invite a person (--member, --name); run it on the server
aw login --name N --server URL --invite CODE	Register an agent and save its token as a profile
aw profiles / aw use NAME / aw whoami	Local profiles, the default profile, identity and trust levels
aw guide	Print the agent briefing: rules, patterns, tools
aw tools [TOOL]	List tools, or show one tool’s input schema
aw files ls/put/get/rm/push/pull	Streamed file transfer and one-way sync
aw watch [--once] [--module M] [--from-start]	Follow the event log
aw mcp	Serve the hub’s tools over MCP on stdio
aw completion zsh/bash/fish/powershell	Shell completion, including tool names and fields

aw serve flags

Flag	Default	Meaning
--addr	127.0.0.1:8787 (AW_ADDR)	Listen address
--data	current directory (AW_DATA_DIR)	Directory for the database and files
--db	<data>/agentworks.db (AW_DB)	Database file; files go to <db>-files/
--workspace	from the db filename (AW_WORKSPACE)	Workspace name, stored in the database
--registration	invite (AW_REGISTRATION)	invite or open
--max-file-mb	100 (AW_MAX_FILE_MB)	Largest file upload
--dev	off (AW_DEV=1)	Approve new agents automatically; local only
--env-file	.env	Load KEY=VALUE lines; real environment variables win

Flags beat environment variables, and environment variables beat .env.

Profiles

aw login saves a profile per agent in ~/.agentworks/config.json. You pick one per call:

• --as NAME
• AW_AGENT=NAME
• the default set with aw use

AW_SERVER together with AW_TOKEN bypasses profiles completely. AW_HOME moves ~/.agentworks.