Reference
The CLI protocol (open standard)
The open protocol any host can implement so AI agents can sign in, pay, deploy, fix failures and export their projects the same way everywhere. Version 1.0, with a conformance suite.
Status: draft for public comment · Editors: the CLI team · Reference implementation: clicloud.app
The CLI protocol is an open way for AI agents to run software on a hosting platform: sign in, pay, deploy, read what went wrong, fix it, and hand control back to a person when they should. Any host can implement it. An agent that learns it once can work on every host that does.
The words MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119.
1. Why a protocol
Agents already deploy code, but every platform speaks its own dialect: different errors, different ways to pay, different ideas of what "deployed" means. That pushes agents into guessing. This protocol fixes the parts an agent has to get right without a person watching:
- Errors an agent can act on. One shape, a stable code, what to do next and when to retry.
- Money an agent can spend safely. Payment over x402, in USDC, with limits.
- A lifecycle an agent can follow. One state machine for every deploy; the running version is never touched by a failed one.
- Plans before changes. Every write can be a dry run.
- Trust you can check. Signed build provenance and an export that runs anywhere.
2. Conformance levels
A host claims levels and extensions in its discovery document (section 3). The conformance suite (section 10) checks every claim.
| Level | A host claiming it MUST |
|---|---|
| core | serve discovery, OpenAPI and a skill file; use the error model (4); accept bearer tokens (5); support projects, services and the deploy lifecycle (6); answer ?dryRun=true on writes (7) |
| payments | take credit over x402 v2 (8) and keep a readable ledger |
| operations | variables with references, one-click databases, custom domains and rollbacks |
| Extension | Meaning |
|---|---|
canary | a new version can take a share of traffic before all of it |
shadow | a new version can run on a copy of live traffic (section 9.1) |
provenance | builds are signed (section 9.2) |
fix-memory | failed deploys carry fixes learned from other failures (section 9.3) |
export | a project can be exported in cli-export/1 (section 9.4) |
approvals | risky changes can wait for a person (section 7) |
flight-recorder | every change is logged with who, why and how to undo it |
ai-gateway | an OpenAI-compatible model endpoint paid from project credit (section 9.5) |
keepers | contract calls on a schedule or an event, through a managed signer (section 9.6) |
3. Discovery
A host MUST answer GET /.well-known/cli-protocol without authentication:
{
"protocol": "cli",
"version": "1.0",
"implementation": { "name": "CLI", "version": "0.2.0" },
"api": "https://host/v1",
"openapi": "https://host/v1/openapi.json",
"skill": "https://host/skill.md",
"errors": "https://host/v1/errors",
"levels": ["core", "payments", "operations"],
"extensions": ["canary", "shadow", "provenance", "fix-memory", "export", "approvals", "flight-recorder"],
"auth": { "bearer": true, "signIn": ["wallet", "email", "github", "project-key"] },
"payments": { "x402": { "version": 2, "networks": ["eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"] }, "currency": "USDC", "unit": "micro" },
"provenance": { "keys": "https://host/.well-known/cli-provenance-keys", "format": "dsse/in-toto/slsa-provenance-v1", "alg": "ed25519" },
"export": { "format": "cli-export/1", "endpoint": "https://host/v1/projects/{id}/export" }
}version follows semantic versioning: hosts on 1.x stay compatible with agents written for 1.0.
skill MUST be a Markdown document an agent can read to learn the host's specifics (sign-in,
funding, the deploy loop, guardrails and a playbook per error code).
4. The error model
Every error response MUST have this body, with an HTTP status that fits it:
{ "error": { "code": "MISSING_ENV", "message": "The app needs DATABASE_URL, which isn't set",
"remediation": ["Link a database or set the variable, then redeploy"], "retry": "after_fix",
"details": { "keys": ["DATABASE_URL"] } } }codeMUST be UPPER_SNAKE and stable. Agents branch on it, never onmessage.retryMUST be one ofyes,no,after_fix,after_topup,after_approval,after_step_up.remediationMUST be a list (possibly empty) of plain-language next steps.GET /v1/errorsMUST list every code the host can return, each withremediationandretry, and MUST include at leastUNAUTHORIZED,FORBIDDEN,NOT_FOUND,VALIDATION,CONFLICT,INSUFFICIENT_FUNDSandRATE_LIMITED.
Deploy failures SHOULD use the build and runtime codes of the reference catalogue (BUILD_COMPILE,
MISSING_ENV, PORT_MISMATCH, HEALTHCHECK_TIMEOUT, RUNTIME_CRASH, RUNTIME_OOM and the rest),
so an agent's playbook carries over between hosts.
5. Identity
Every authenticated request carries Authorization: Bearer <token>. A host MUST return 401 with
code UNAUTHORIZED when the token is missing or bad, and 403 FORBIDDEN when it's valid but not
enough. How tokens are obtained is up to the host and described in its skill file; the reference
implementation offers wallet sign-in (SIWE and Solana), email, GitHub and project keys with roles
(owner, admin, developer, viewer) and scopes. Reading secrets SHOULD need its own scope and,
for people with a second factor, a fresh one (retry: "after_step_up").
6. Projects, services and deploys
The core resources, with the paths of the reference implementation (hosts MAY add more):
POST /v1/projects, GET /v1/projects, GET /v1/projects/:id | projects, with a USDC balance |
POST /v1/projects/:id/services | a service: {"name", "source": {"type": "github"|"git"|"image"|"upload", …}, "port"?} |
POST /v1/services/:id/deploys | start a deploy (optional {"commit"}); returns it in queued |
GET /v1/deploys/:id, GET /v1/deploys/:id/logs | its state, error and logs |
POST /v1/deploys/:id/rollback | redeploy an earlier healthy image (operations level) |
Every deploy MUST move through this state machine and nothing else:
queued ──► building ──► deploying ──► healthy ──► superseded
│ │ │
└► cancelled└──► failed ◄─┘ (deploying ──► cancelled: a discarded shadow)A failed deploy MUST NOT change what is serving traffic. A failed deploy's error MUST follow
section 4. IDs SHOULD carry a type prefix (prj_, svc_, dep_).
7. Dry runs, intent and approvals
- Every write in the core level MUST accept
?dryRun=true(orX-CLI-Dry-Run: true) and answer 200 with{"dryRun": true, "plan": {…}}without changing anything. A plan SHOULD say what would change, what it costs per hour before and after, and whether it would fail or need approval. - Any write MAY carry
X-CLI-Intent: <one sentence>; hosts SHOULD record it with the change. - With the
approvalsextension, a write the project's rules hold back answers 403 withretry: "after_approval"and an approval id; the agent resends withX-CLI-Approval: <id>once a person approves.
8. Payments
Hosts on the payments level take credit over x402 version 2:
- The agent calls
POST /v1/projects/:id/topup?amount=<micro-USDC>. - The host answers 402 with a
PAYMENT-REQUIREDheader: base64 JSON withx402Version: 2andaccepts[], one option per network, each withnetwork,asset,amountandpayTo. - The agent pays and resends with
PAYMENT-SIGNATURE; the host settles and answers 200 with the newbalance.
Amounts are integers in micro-USDC (1 USDC = 1,000,000). Credit SHOULD be pegged to the dollar. A host MUST NOT take payment for a write that a dry run says would fail.
9. Extensions
9.1 Shadow traffic (shadow)
POST /v1/services/:id/shadow {"percent", "minutes", "includeWrites"?, "promoteIfHealthy"?} builds
a new version and runs it beside the live one. The host copies percent of live requests to it
(only GET and HEAD unless includeWrites) and discards its responses: callers only ever see the
live version. The deploy stays in deploying with shadow.state of watching, then finished
with a verdict (good, worse or inconclusive) comparing 5xx rate and p95 latency. POST /v1/deploys/:id/shadow {"action": "promote"|"discard"} decides; a host MAY promote by itself when
asked and the verdict is good, and SHOULD discard an undecided shadow after a day. A shadow MUST NOT
run release commands (they would change the live version's data).
9.2 Signed build provenance (provenance)
For every image it builds, the host signs an in-toto Statement v1 with a SLSA Provenance v1 predicate, in a DSSE envelope, with Ed25519:
subject[0]: the image name anddigest.sha256.predicate.buildDefinition.buildType:https://clicloud.app/protocol/build/v1;externalParameters.source:{type, repository, ref, rootDir};resolvedDependencies: the git commit as{uri: "git+<repo>", digest: {gitCommit}}.predicate.runDetails: the builder id andinvocationId(the deploy id), with start and finish times.
GET /v1/deploys/:id/provenance returns the envelope. GET /.well-known/cli-provenance-keys
returns {"keys": [{"keyId", "alg": "ed25519", "publicKey": "<base64 of the 32-byte key>"}]};
keyId is the first 16 hex characters of the SHA-256 of the raw public key. Images the host didn't
build (prebuilt) get no attestation.
9.3 The shared memory of fixes (fix-memory)
A failed deploy's response MAY carry knownFixes, and GET /v1/deploys/:id/fixes MUST return
{"fingerprint", "signature", "suggestions": [...], "related": [...]}. Each suggestion is {change, description, successes, failures, projects, confidence, yours}, where change lists variables
added, removed or changed by name only, settings that changed, and whether the code changed.
Hosts MUST NOT store or share values, raw logs, or project and repository names; MUST NOT show a fix
to other projects until it worked in at least two; and MUST let a project opt out.
9.4 The exit export (export)
GET /v1/projects/:id/export returns a .tar.gz holding docker-compose.yml (every app and
database, on one network, with the same hostnames as on the host), env/<service>.env (resolved
variables), databases/<service>.dump, README.md and cli-export.json:
{ "format": "cli-export/1", "exportedAt": "…", "project": { "id", "name", "environment" },
"services": [ { "name", "host", "kind": "app"|"postgres"|"mysql"|"redis"|"mongo",
"source": { "type", "repository"?, "ref"?, "image"?, "rootDir"? }, "port", "healthcheckPath",
"startCommand", "releaseCommand", "plan": { "cpu", "memoryMb" }, "replicas", "volume",
"variables": ["NAMES", "ONLY"], "domains": [], "cron": [ { "name", "schedule", "command" } ], "dump"? } ],
"notIncluded": [] }The archive holds secrets: it MUST be guarded like reading them (section 5) and logged.
GET /v1/projects/:id/export/manifest returns cli-export.json alone, without secrets. A host that
supports export SHOULD also import cli-export/1.
9.5 The AI gateway (ai-gateway)
POST /v1/ai/chat/completions MUST accept OpenAI's chat completions format and answer in it, with
usage and the call's cost in cli.cost (micro-USDC). It is authorized by a project-scoped AI key
(Bearer clai_…) or by a project credential plus X-CLI-Project. GET /v1/ai/models lists models
with pricing.inputPerMillion and pricing.outputPerMillion. A host MUST charge only for tokens
used, MUST NOT charge for a call the provider failed, and MUST refuse a call whose worst-case cost
exceeds the balance (INSUFFICIENT_FUNDS) or the project's monthly AI cap (AI_CAP_REACHED).
stream: true MUST produce chat.completion.chunk events ending in data: [DONE], with usage and
cli.cost in the last chunk, and refusals MUST come before the stream starts. tools and
tool_choice follow OpenAI's format. POST /v1/ai/embeddings is OpenAI-compatible. A request with
no credentials MAY be answered with an x402 challenge for the call's worst-case price, each payment
buying one call.
9.6 Keepers (keepers)
POST /v1/projects/:id/keepers creates a job that calls one function (a human-readable signature
and arguments, with {{now}}, {{block}} and {{event.<arg>}} placeholders) through one of the
project's managed signers, on a cron schedule or an event ({address, abi}), optionally only
when a view condition returns true. The signer's policy MUST apply to every transaction. Every run
MUST be logged as sent (with the transaction hash), skipped or failed, with the reason.
10. Conformance testing
npx tsx scripts/conformance.ts https://host [--token <token>] [--project <id>] [--json]The suite reads the discovery document and checks every level and extension the host claims. It never spends money (the payment check stops at the 402) and never creates anything (writes are dry runs). Without a token, checks that need one are skipped. A host passes when no check fails.
11. Versioning and governance
Changes that would break an agent written for 1.0 need 2.0. Additions (new codes, fields, extensions) are minor versions. This specification is proposed under CC BY 4.0 and the conformance suite under Apache 2.0, so other hosts can implement and test against it freely; final licensing is the editors' decision before 1.0 leaves draft.