APCO for AI agents

APCO Cloud is built to be driven by agents as much as by humans. Every surface — CLI, MCP, HTTP — is designed around the same principles: machine-parseable output, stable error codes, and no secrets in output.

Why APCO is agent-friendly

• --json on every command. In --json mode, stdout is exactly one JSON object (the envelope); human diagnostics and progress go to stderr. You never have to scrape ANSI output or guess where the payload ends.
• A stable envelope. Success is { "ok": true, "operation": "...", "warnings": [], ... }; failure is { "ok": false, "operation": "...", "error": { "code", "message", "hint" } }. The hint tells you what to do next; the code tells you whether retrying can help.
• Stable error codes. CLOUD_UNAUTHORIZED, DEPLOY_FAILED, DESTRUCTIVE_CONFIRMATION_REQUIRED, QUOTA_EXCEEDED, ... — enumerated in the agent contract and mapped to exit codes.
• Secrets are redacted. Fields whose keys look secret (token, password, apiKey, value, ...) come back as "[redacted]" in JSON output; env-var listing surfaces names only.
• Headless auth. Set APCO_TOKEN=<api key> and every command works without an interactive login — it takes precedence over any stored credentials. Scoped tokens (created in the dashboard) let you hand an agent exactly the permissions it needs, e.g. deploy + logs:read but not env:read.
• Explicit destructive semantics. Destructive commands (projects delete, db disable) refuse to run in --json/non-TTY mode without --yes, failing with DESTRUCTIVE_CONFIRMATION_REQUIRED instead of prompting. Nothing ever blocks waiting for a human.
• An MCP server. apco mcp exposes the platform as typed MCP tools for Claude Code, Cursor, and any other MCP client — see MCP server.

Three ways in — which to use

Surface	Use when	Notes
MCP server (apco mcp)	You are an agent running inside an MCP-capable harness (Claude Code, Cursor, ...)	Typed tools with schemas; no shell quoting or output parsing; auth resolves from the CLI login or APCO_TOKEN. The natural default for interactive agents. See MCP server.
CLI with --json	You can run shell commands; you need something MCP doesn't expose (verify, env pull/push to files, db disable, db migrate, dev --sync); or you're scripting CI	One JSON object per invocation; exit codes signal outcome classes; --yes for automation. See the CLI reference.
Raw HTTP API	No CLI available, custom tooling, or long-lived services	https://apco.space/api/v1/... with an x-api-key header. Async actions return 202 with an id to poll. See the HTTP API reference.

A good rule: prefer MCP when your harness supports it, fall back to the CLI for the few operations MCP doesn't cover, and use raw HTTP only when you're building your own integration.

The 60-second agent flow

apco doctor --json                     # one-shot diagnostic (auth/api/manifest/project/db); always exit 0
apco whoami --json                     # verify credentials
apco manifest validate --json          # check apco.yml before uploading
apco deploy --json --yes               # pack, upload, build, wait for running
apco verify --json                     # poll the live URL until HTTP 200

# When something fails:
apco status --json
apco logs --json                       # build log of the latest deployment
apco logs --json --runtime --lines 200 --since 15m --grep "error"
apco rollback --json                   # restore the previous deployment

Start with apco doctor when anything is off. It runs six checks (auth, api, manifest, project, dev-channel, database) and always exits 0 — read the healthy boolean and each check's status (pass/fail/warn/skip) rather than the exit code. No secrets appear in its output. See the CLI reference.

Ground rules

Read the agent contract for the full set; the non-negotiables:

1. Always pass --json for output you parse; --follow streams and is incompatible with it.
2. Never print, log, or commit env-var values, API keys, .env* files, or ~/.config/apco/config.json.
3. Don't guess project ids — read them from apco projects list --json or apco status --json.
4. On failure, read error.code and error.hint before retrying; auth errors will not fix themselves by retrying.

Machine-readable index

The docs site publishes /llms.txt — a compact index of the platform (manifest schema, MCP tools, key concepts) built for LLM ingestion. Point your agent's context loader at it.

Where to go next

• MCP server — setup and the full tool table.
• Agent contract — auth, envelopes, exit codes, error codes, scopes.
• CLI reference · HTTP API · Error codes · Token scopes