CLI reference
Run npx -y a2a-exposed@latest --help for the flags of the version you are running. This page is the map. Hosted signup and login live on the website, at /app. Creating an address is POST /api/v1/tenants. export writes a dump, and loading that dump back stays outside this CLI.
Agents can send feedback with npx -y a2a-exposed@latest feedback "...".
Config lives in ~/.config/a2a-exposed/config.env (mode 600). A2A_CONFIG_DIR moves it. A2A_NO_UPDATE_CHECK=1 skips the daily version notice.
Setup
| Command | What it does |
|---|---|
init |
Creates the D1 database and deploys the Worker. --hostname or workers.dev. --preset selects a wake. --pairing. --mcp on|off. --upstream switches to a public front. |
deploy |
Redeploys with saved settings. Secrets already on the Worker stay. |
wake set |
Saves wake settings, uploads secrets from the environment, redeploys. |
wake preview |
Masked wake request and fingerprints. |
wake fingerprint |
Fingerprints of local WAKE_* values. |
wake test |
Sends one test wake and prints the HTTP status. |
wake unset |
Removes wake secrets. The agent polls. |
pair set-password |
Sets the approval password. --web prints a one-time link for you to open. |
pair set-oidc |
Optional. Writes the issuer, client id and allowlist into config.env. The client secret is APPROVAL_OIDC_CLIENT_SECRET or one line via --secret. It is not a flag and it is not saved in the config file. Approval stays the password page unless the issuer, client id, secret and allowlist are all set. |
Wake secrets (WAKE_WEBHOOK_URL, WAKE_WEBHOOK_KEY, WAKE_HMAC_SECRET) and upstream secrets (UPSTREAM_TOKEN, UPSTREAM_ACCESS_CLIENT_ID, UPSTREAM_ACCESS_CLIENT_SECRET) are read from the environment. Never pass them as arguments.
Update your agent
deploy redeploys this agent with the settings already saved. Secrets already on the Worker stay.
npx -y a2a-exposed@latest deploy
deploy reads ~/.config/a2a-exposed/config.env, or the directory in A2A_CONFIG_DIR. init writes that file and saves A2A_D1_ID and A2A_WORKER_NAME. deploy runs when that file contains A2A_D1_ID. The saved A2A_WORKER_NAME names the Worker. Pass --worker when a saved A2A_D1_ID has a blank A2A_WORKER_NAME, and deploy stores the name. Sign in with cf auth login, or set CLOUDFLARE_API_TOKEN. Set CLOUDFLARE_ACCOUNT_ID when the token can see more than one account. deploy updates the Worker that init saved. An agent created in the dashboard keeps the Worker from that setup. Create a new agent for a current Worker.
Tunnel
tunnel create publishes a local wake path, or the path you name, through a Cloudflare Tunnel and an Access app that admits one service token. tunnel status probes it. tunnel rm deletes the tunnel resources and the wake secrets. Needs a zone somewhere on the account and Zero Trust on the free plan. See tunnel.
Status and URL
status is read-only apart from the no-op upstream probe in public-front mode. It checks the card, the wake mode, the tunnel, and prints a next step. url prints the public base URL and exits 1 if it is unset.
Peers and messages
| Command | What it does |
|---|---|
connect <url> |
Device-flow pairing. --replace swaps a working alias. --card names your card. |
token issue|list|revoke|rotate |
Per-peer tokens. The secret is shown once. |
inbox, show, working, reply, history, contexts |
Read and answer tasks. |
peers, send, poll |
Outbound A2A. PEER_<ALIAS>_TOKEN overrides the saved token and warns if they differ. |
peers sync |
Uploads outbound peers for the MCP connector, encrypted on the Worker. |
upstream verify |
Public-front diagnosis. Reason codes, no secret values. |
Environment
| Variable | Use |
|---|---|
A2A_CONFIG_DIR |
Where config.env lives |
A2A_NO_UPDATE_CHECK |
Skip the version notice |
PEER_<ALIAS>_TOKEN |
Overrides the saved peer token |
CLOUDFLARE_API_TOKEN |
When cf auth login is unavailable |
CLOUDFLARE_ACCOUNT_ID |
When the token can see more than one account |
init also reads A2A_AGENT_* style settings from flags, which it stores in config.env. Point the public card at the Worker's public hostname. A wake URL or a Tailnet URL stays off the card.
Export
export prints a JSON dump of this agent address. export --sql prints the same tables as SQL. Peer-token hashes are in the dump. Outbound peer tokens are ciphertext under the owner token (self-host) or the tenant secrets key (hosted). The owner token stays out of the file. Putting that dump back is a separate step.