a2wave-cli

a2wave CLI

Use the a2wave command-line tool to manage the a2wave Agent orchestration platform.

Checks Before You Start

1. Before debugging authentication, URL, token, or backend connectivity issues, run a2wave status first.
2. If the URL is not yet configured, set it with a2wave config set-url <url>; you can also pass --url <url> on a single command, or set A2WAVE_URL.
3. Login and URL configuration are two separate things: a2wave login runs OAuth SSO via your identity provider (IdP) and writes local credentials.
4. For resource arguments that accept <id|name>, you can pass an ID or an exact name; an ID is used directly, while a name is resolved via the list API.

Platform Install (setup)

a2wave setup --image a2wave:latest          # interactive: dir + port prompts, then docker compose up + health wait
a2wave setup --yes --image a2wave:latest    # non-interactive with defaults (~/a2wave, port 3502)
a2wave setup --yes --image a2wave:latest --dir /srv/a2wave --port 3510 --base-url http://192.168.1.10:3510
a2wave setup --no-start --image a2wave:latest  # generate .env + docker-compose.yml only
a2wave setup --yes --database-url postgres://a2wave:[email protected]:5432/a2wave  # EXPERIMENTAL: external PostgreSQL backend
a2wave setup --yes --with-postgres          # EXPERIMENTAL: bundle a postgres:16-alpine sidecar (password generated into .env)
a2wave setup --upgrade --image a2wave:1.4.0 # move an existing install to a new image, keeping its data
a2wave setup --down                         # uninstall: requires typing the install dir path to confirm
a2wave setup --reset-password               # forgot the admin password: reset it from a running install

• --upgrade is the only supported way to move an install to a new image — never tell a user to hand-edit docker-compose.yml. The image lives in .env as A2WAVE_IMAGE (the compose file reads it via ${A2WAVE_IMAGE:-...}), so the upgrade rewrites one env key, backs the data volume up to a2wave-data-<stamp>.tar.gz in the install dir first (--no-backup skips it), then pulls and recreates only the a2wave service and waits for liveness and readiness. It never deletes the data volume, and everything else in .env survives byte-for-byte. A legacy install with a hardcoded image line is migrated to the variable automatically when the file still matches the generated layout; a hand-edited compose file is refused with the exact edit to make rather than guessed at. If the new image fails to start or fails its checks, the previous image is restored, brought back up, and health-verified before the rollback is reported as successful. Cannot be combined with --down, --reset-password, --base-url, --port, or --no-start.

• --image is optional: it defaults to ghcr.io/lilithgames/a2wave:<cli-version>, the published image matching the CLI's own version (the platform and the CLI share one version line). Pass it only to install a locally built or mirrored ref. Never invent a registry URL.

• Requires Docker + Compose v2, and a nonexistent or empty install directory (setup owns the whole dir; --down deletes it recursively). The generated .env holds AUTH_SECRET (mode 0600); no admin password is generated — the first web visit asks to set it.

• Once healthy, and only on a TTY without --yes, setup also offers to set the admin password itself (prompted twice, echo suppressed, POSTed to /api/auth/setup on localhost) instead of leaving it to the first web visit. --yes always skips this, even on a TTY.

• --reset-password recovers a forgotten admin password from an existing install: it runs the in-image recovery script via docker compose exec against the running container, so the new password is typed inside the container, never through the CLI process, argv, or the environment — there is deliberately no --admin-password flag. Takes effect immediately, no restart. Mutually exclusive with --down. Do not try to recover via the ADMIN_PASSWORD env var — it only bootstraps an admin that has no password yet and is silently ignored once one is set.

• The CLI config is saved only after the health check passes, and the login token is kept only when the instance URL is unchanged (a token is never sent to a different host).

• --database-url / --with-postgres select the EXPERIMENTAL PostgreSQL backend (SQLite stays the default; there is no SQLite → PostgreSQL data migration — the install starts from an empty database). --database-url must be a postgres:///postgresql:// URL and points at an external server; --with-postgres instead adds a postgres:16-alpine sidecar to the generated compose file and derives DATABASE_URL with a generated hex password kept only in the 0600 .env. The two flags are mutually exclusive, and both are rejected with --upgrade (an upgrade never rewrites .env). To switch an existing install, edit DATABASE_URL in .env and docker compose up -d — the generated compose reads ${DATABASE_URL:-/app/data/a2wave.db}. Warn users that a localhost database URL is unreachable from inside the container (use host.docker.internal or the host IP), and that on a PostgreSQL install the pre-upgrade backup covers only the data volume, not the database — suggest pg_dump first.

• setup rejects unrecognized options before Docker preflight or file generation. The PostgreSQL flags were added after CLI v0.7.2 and are absent from the published [email protected] package; confirm a2wave setup --help lists them. If a documented flag is unknown, install a newer CLI; never assume the option was applied or continue with the default backend.

• --base-url is for LAN/reverse-proxy access (drives CORS_ORIGIN and cookie security); the health check always probes http://localhost:<port>.

• --down destroys the container, the data volume, and the install directory irreversibly. Interactive confirmation demands typing the directory path; non-interactive use demands the explicit --yes-destroy-all-data flag (--yes alone never bypasses it). It refuses directories missing the .a2wave-install marker.

• --reset-password recovers a forgotten admin password from an existing install: it runs the in-image recovery script via docker compose exec --user appuser, so the new password is typed inside the container, never through the CLI process, argv, or the environment — there is deliberately no --admin-password flag. It bumps the admin's tokenVersion, so every existing session/token is revoked and everyone must log in again. Takes effect immediately, no restart. Requires an interactive terminal; rejects --yes and is mutually exclusive with --down. Do not try to recover via the ADMIN_PASSWORD env var — it only bootstraps an admin that has no password yet and is silently ignored once one is set.

• Never suggest raw docker compose down -v / rm -rf for uninstalling an a2wave install — the setup command's gates exist to prevent destroying unrelated projects.

Authentication and Configuration

a2wave login
a2wave status
a2wave config set-url http://localhost:3502
a2wave config get
a2wave logout

• Prefer OAuth login. Only use a2wave login --password for older username/password instances.
• Do not print tokens, API keys, appSecret, or endpointApiKey unless the user explicitly asks to view a newly generated value and needs to save it.

Agent Management

Common read/update commands:

a2wave agents list
a2wave agents get <agent-id-or-name>
a2wave agents diagnose <agent-id-or-name>
a2wave agents update <agent-id-or-name> --system-prompt "..."
a2wave agents update <agent-id-or-name> --add-skill <skill-id-or-name>
a2wave agents update <agent-id-or-name> --add-mcp <mcp-id-or-name>

Lifecycle commands:

a2wave agents publish <agent-id-or-name> --channels api,feishu --auth-type api_key
a2wave agents stop <agent-id-or-name>
a2wave agents resume <agent-id-or-name>
a2wave agents clone <agent-id-or-name>
a2wave agents delete <agent-id-or-name>
a2wave agents regenerate-api-key <agent-id-or-name>

Stats, artifacts, and memory:

a2wave agents stats <agent-id-or-name>                       # KPI / number of askers / channel distribution

a2wave agents artifacts list <agent-id-or-name>              # List artifacts
a2wave agents artifacts download <artifact-id> --out ./x.zip # Download an artifact
a2wave agents artifacts delete <artifact-id>

a2wave agents memory stats <agent-id-or-name>
a2wave agents memory search <agent-id-or-name> --query "..."
a2wave agents memory reindex <agent-id-or-name>
a2wave agents memory consolidate <agent-id-or-name>

"Publish settings" are done via agents publish + agents update; run records use the runs commands and conversations use the chat commands (see below).

Member management commands:

a2wave agents members list <agent-id-or-name>
a2wave agents members add <agent-id-or-name> --user <user-id-or-username-or-email> --role viewer
a2wave agents members update <agent-id-or-name> --user <user-id-or-username-or-email> --role editor
a2wave agents members remove <agent-id-or-name> --user <user-id-or-username-or-email>

Only the owner can manage members. Valid member roles are viewer and editor.

Declarative Agent Apply

For reproducible Agent configuration and CI scenarios, prefer agents apply:

a2wave agents apply --example > agent.yaml
a2wave agents apply -f agent.yaml --dry-run
a2wave agents apply -f agent.yaml

Key rules:

• name is the idempotent identity key.
• Reference fields can use an ID or a name: provider, skills, skillGroups, mcpServers, kbDocuments, workspace.source.
• Sensitive values can be written as ${ENV_VAR} or ${ENV_VAR:-default}; the CLI expands them from environment variables at apply time.
• If the YAML includes a publish block, apply creates/updates the Agent and then publishes it. Use --no-publish to keep it in draft state.
• When the YAML involves publish channels, Feishu configuration, scheduled configuration, Provider authentication, or environment variables, use --dry-run before making production changes.

Skill Management

a2wave skills list
a2wave skills get <skill-id-or-name>
a2wave skills create --name my-skill --content-file ./SKILL.md --group <group-id-or-name>
a2wave skills create --file ./skill.zip          # Upload .md/.zip to create
a2wave skills create --url https://skills.sh/owner/repo/skill
a2wave skills install https://skills.sh/owner/repo/skill
a2wave skills install https://github.com/owner/repo --skill path/to/my-skill
a2wave skills install https://github.com/owner/repo --all --group <group-id-or-name>
a2wave skills check-update <skill-id-or-name>
a2wave skills update-remote <skill-id-or-name> --strategy preserve-local
a2wave skills update <skill-id-or-name> --content-file ./SKILL.md
a2wave skills update <skill-id-or-name> --file ./skill.zip
a2wave skills delete <skill-id-or-name>

Use --file for full-package replacement/upload (.md or .zip). When you only need to modify the SKILL.md instruction body, use --content-file. Remote updates are always explicit: run check-update first, then choose abort, preserve-local, or overwrite if the three-way comparison reports conflicts.

MCP Server Management

a2wave mcp list
a2wave mcp get <mcp-id-or-name>
a2wave mcp create --name fs --type stdio --command npx --arg -y --arg @modelcontextprotocol/server-filesystem --env KEY=val
a2wave mcp create --name remote --type http --endpoint https://host/mcp --header "Authorization=Bearer x"
a2wave mcp update <mcp-id-or-name> --enabled
a2wave mcp delete <mcp-id-or-name>
a2wave mcp tools <mcp-id-or-name>                # Connect and list the tools exposed by this server (troubleshooting)

--arg / --header / --env can be repeated. Use --endpoint for the sse/http service address (to avoid the global --url). For the group type, provide groupConfig with --config-file <json>.

SCM Source Management

a2wave scm list
a2wave scm get <scm-id-or-name>
a2wave scm create --name repo --type git --repo-url https://git/x.git --branch main
a2wave scm create --name custom-repo --type git --local-path /data/repo --repo-url https://git/x.git
a2wave scm create --name p4src --type p4 --local-path /data/p4 --p4port host:1666 --p4user u --p4client ws
a2wave scm update <scm-id-or-name> --enabled
a2wave scm delete <scm-id-or-name>
a2wave scm sync <scm-id-or-name>                 # Trigger a background sync
a2wave scm check <scm-id-or-name>                # Check connectivity
a2wave scm status <scm-id-or-name>               # Sync / CodeGraph status

Git uses platform-managed storage when --local-path is omitted. P4 always requires --local-path. For complex structures such as git multi-repo, fall back to --config-file <json>.

Knowledge Base (KB Document) Management

a2wave kb list
a2wave kb get <kb-id-or-name>
a2wave kb create --name doc --feishu-url <url> --feishu-app-id <id> --feishu-app-secret <secret>
a2wave kb create --name doc --notion-url <url> --notion-token <token>   # Notion source (mutually exclusive with --feishu-url)
a2wave kb upload --file ./notes.md               # Upload a local .md/.txt (document name taken from the file name)
a2wave kb update <kb-id-or-name> --auto-sync
a2wave kb update <kb-id-or-name> --notion-url <url> --notion-token <token>
a2wave kb delete <kb-id-or-name>
a2wave kb sync <kb-id-or-name>                    # Re-fetch the Feishu / Notion document
a2wave kb content <kb-id-or-name>                 # Print the cached body (troubleshooting)

Provider Management

Providers are preset entities (cannot be created or deleted) and are entirely read-only:

a2wave providers list
a2wave providers get <provider-id-or-name>
a2wave providers login-status pi                  # Kind: cursor | claude-code | codex | opencode | qoder | trae | kimi | pi
a2wave providers dependents <provider-id-or-name>  # Agents that depend on this Provider

There is no set-models: Providers store no model catalog. The list of models an Agent may pick is probed from the CLI against that Agent's own credentials, so it always matches what the account can actually run. PATCH /api/providers/:id answers 403.

Run

a2wave runs list
a2wave runs list --agent <agent-id-or-name>
a2wave runs list --status failed --page 2 --limit 50
a2wave runs get <run-id>
a2wave runs trigger <agent-id-or-name> --intent "..."
a2wave runs cancel <run-id>
a2wave runs rerun <run-id> [--wait]
a2wave runs logs <run-id> [-o run.ndjson]

runs trigger creates a Run and streams the execution logs. If a Run fails, first check a2wave runs get <run-id>, then run a2wave agents diagnose <agent>, and only then modify the Agent configuration.

runs cancel stops a queued or running Run. runs rerun replays one with its original intent and attachments — the server starts it, so never follow it with an execute call; --wait polls to a terminal status and exits 1 on failure. runs logs fetches the NDJSON sidecar — not subject to the MAX_STREAM_LOGS cap that truncates the DB copy shown by runs get, though the sidecar has its own 256 MiB cap and may carry dropped markers under sustained backpressure.

--status narrows the current page only (the API has no status filter); with --json the payload carries a filter block so a partial count is not mistaken for a total.

Chat

a2wave chat send <agent-id-or-name> -m "your question"
a2wave chat send <agent-id-or-name> -m "follow-up" --chat-id <chat-id>
a2wave chat send <agent-id-or-name>            # interactive session (needs a TTY)
a2wave chat list <agent-id-or-name>
a2wave chat messages <agent-id-or-name> <run-id>

The one-shot form is chat send, not bare chat <agent>. chat list prints two different ids: the run_xxx (pass to chat messages) and the chat-id (pass to --chat-id) — giving --chat-id a run id silently starts a new conversation instead of resuming it.

When the Agent has no free concurrency slot the run is accepted and queued, not rejected; the CLI reports the runId so you can follow it with runs get.

Evaluation

a2wave eval sets list <agent-id-or-name>
a2wave eval sets create <agent-id-or-name> --name regression
a2wave eval cases add <agent> <set> --name greeting --request "hi" --expected "hello"
a2wave eval cases import <agent> <set> -f cases.yaml
a2wave eval run <agent> --set <set> --wait --fail-on-fail
a2wave eval tasks get <agent> <task-id>
a2wave eval tasks verdict <agent> <task-id> <result-id> --verdict pass

Replays an evaluation set against the Agent's current config and freezes a provider/model/prompt snapshot. --fail-on-fail exits 1 when a case carries a fail verdict or errored during replay, which makes it usable as a CI regression gate. Verdicts are manual in v1.

eval cases import has no bulk endpoint and no transaction: a mid-way failure leaves a partial import, and the CLI names the cases that landed so a retry does not duplicate them.

Machine-readable output

Read commands accept --json and print the raw API payload, so scripts never scrape columns:

a2wave agents list --json | jq -r '.data[] | select(.publishStatus=="published") | .id'
a2wave chat send my-bot -m "ping" --json | jq -r '.data.reply'

Credentials are redacted by default (********). The API returns secrets in plaintext to an owner/editor, but CLI output lands in terminal scrollback, shell history and CI logs — pass --show-secrets only when piping to a secure consumer.

Import and Export

a2wave agents export <agent-id-or-name> -o agent.zip
a2wave agents import ./agent.zip
a2wave agents import-url <remote-export-url>

Use import/export to migrate an Agent package and its dependent MCP Servers and Skills between different a2wave instances.

Update

Always use:

a2wave update

a2wave update updates the a2wave-cli npm package. It queries the npm default registry unless $A2WAVE_NPM_REGISTRY is set, which lets you point it at a mirror. It does not install or update this companion skill — do that through whatever mechanism distributes skills on your machine.

After the Skill is updated, if the update needs to be reloaded into the model context, remind the user to restart the AI Agent application.

Security Rules

• For destructive or broad-impact changes, run a read command or --dry-run first, and show the target to the user.
• Do not bypass platform authentication, and do not suggest anonymous invocation.
• Maintain a2wave's product boundary: a2wave orchestrates mature agent CLIs and extensions; it does not implement a new execution engine, sandbox runtime, or third-party trigger adapter.