CLI

Install Node.js 22.19 or later, then install the CLI:

npm install -g @maxceem/agw
agw --help
agw deployment status --json

The default destination is the hosted API. The first provider, provider-gateway or application creation initializes a recoverable account and saves its credential privately. For example, run agw provider add --type openai --browser --no-open. Help, status, lists and validation never create an account. For an existing account, run agw account login and enter a management key through the hidden prompt, or pipe it with --key-stdin. For your own deployment, run agw deployment setup --name my-gateway --no-domain. It drives Wrangler itself and fetches the Worker, console and migrations it installs: one archive from the project's GitHub release, checked against a hash built into the CLI and then cached, so a source checkout is not required. See Deploy to Cloudflare for the offline route.

Human handoffs

Run agw account claim to establish human ownership. The CLI prints a browser URL. Open it in a browser outside the agent's visible session, compare the account shown with the terminal, and create your sign-in on that page. This account must be claimed by a new person, so if the browser is already signed in as someone with an account, the page asks you to sign out first. The page shows the account being claimed and the person approving, and one button completes it. The CLI stays connected afterwards, so an interrupted command can simply continue; to end that access later, revoke its key from the console.

Provider commands offer a browser handoff for write-only secrets. Share the URL with the person supplying the credential. The page shows the provider, destination and proposed changes. Secrets never appear in CLI output or later reads. Poll with the operation command shown by the CLI; handoffs last 15 minutes.

Daily workflow

agw account status --json
agw provider list --json
agw app list --json
agw usage show --month 2026-09 --json
agw app --help
agw provider --help

Use the command's --help for its exact flags. Read an app before editing it. Application updates carry the revision read from the server and reject a concurrent change; reread and merge deliberately. Add and update with --file preserve the complete validated configuration, including native endpoint parameters. They do not transfer credentials or usage to another deployment. Build that file from agw app show <app-id> --json, keeping name, config and status from result.app.

agw app snippet <app-id> prints a request that app can send: curl for a server app, Swift for an iOS one. Creating an app prints it too. It is built from that app's own providers, allowed paths and priced models, and stands named placeholders in — PROVIDER_SLUG, MODEL — for anything not set up yet, so you always get something to run and can see what is still missing.

Application keys are written only to a private file. Select a path with --key-output, or use the default managed private file. Use hidden prompts or --key-stdin when connecting with an existing management key. Never put secrets in command arguments, source control, chat or logs. The CLI does not make inference requests as a setup check. Provider inference must be requested explicitly.

Output and recovery

--json writes one JSON document to stdout with schemaVersion, ok and either result or error. Progress goes to stderr. Without --json the same result is printed as plain text to read, and a failure is printed to stderr instead of stdout. Exit codes are 0 for success, 2 for input errors, 3 for remote failures, 4 for state or authentication recovery, and 5 for a wait timeout. A timeout leaves the operation pending.

A request refused by a limit says which one: error.message names the limit, its ceiling and what the count is shared across, and error.details carries scope, limit, windowSeconds, retryAfterSeconds and resetAt. Wait retryAfterSeconds and repeat the same command.

The CLI keeps one active connection. Its private state lives in $XDG_STATE_HOME/agw or ~/.local/state/agw, and %LOCALAPPDATA%/agw on Windows. It saves initiation proofs before requests and credentials before reporting success. Repeat a failed command with the same state to recover a lost response; do not delete state or invent a new request proof. A recovered application key can finish writing to a new unused output file without issuing another key.

A short lock guards each write to that state rather than the command around it, so other commands still run beside an agw operation wait that is polling. A deployment installed with agw deployment setup keeps its vault key in a file of its own under vault-keys/ in the same directory, and keeps nothing else from the install. Back that directory up privately: losing the vault key makes stored provider credentials unreadable.

Remote key replay lasts 15 minutes. After it expires, recovery identifies the existing resource; inspect it and replace its key intentionally. Durable receipts prevent duplicate creation. Account usage includes retained records from deleted apps; the response describes any historical attribution limitation.

agw deployment update --dry-run and agw deployment domain --hostname ai.example.com --dry-run inspect changes without deploying. Updating a mobile app's embedded gateway URL remains a separate application release.