Docs menu

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:

  1. Errors an agent can act on. One shape, a stable code, what to do next and when to retry.
  2. Money an agent can spend safely. Payment over x402, in USDC, with limits.
  3. A lifecycle an agent can follow. One state machine for every deploy; the running version is never touched by a failed one.
  4. Plans before changes. Every write can be a dry run.
  5. 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.

LevelA host claiming it MUST
coreserve 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)
paymentstake credit over x402 v2 (8) and keep a readable ledger
operationsvariables with references, one-click databases, custom domains and rollbacks
ExtensionMeaning
canarya new version can take a share of traffic before all of it
shadowa new version can run on a copy of live traffic (section 9.1)
provenancebuilds are signed (section 9.2)
fix-memoryfailed deploys carry fixes learned from other failures (section 9.3)
exporta project can be exported in cli-export/1 (section 9.4)
approvalsrisky changes can wait for a person (section 7)
flight-recorderevery change is logged with who, why and how to undo it
ai-gatewayan OpenAI-compatible model endpoint paid from project credit (section 9.5)
keeperscontract 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:

JSON
{
  "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:

JSON
{ "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"] } } }
  • code MUST be UPPER_SNAKE and stable. Agents branch on it, never on message.
  • retry MUST be one of yes, no, after_fix, after_topup, after_approval, after_step_up.
  • remediation MUST be a list (possibly empty) of plain-language next steps.
  • GET /v1/errors MUST list every code the host can return, each with remediation and retry, and MUST include at least UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION, CONFLICT, INSUFFICIENT_FUNDS and RATE_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/:idprojects, with a USDC balance
POST /v1/projects/:id/servicesa service: {"name", "source": {"type": "github"|"git"|"image"|"upload", …}, "port"?}
POST /v1/services/:id/deploysstart a deploy (optional {"commit"}); returns it in queued
GET /v1/deploys/:id, GET /v1/deploys/:id/logsits state, error and logs
POST /v1/deploys/:id/rollbackredeploy 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 (or X-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 approvals extension, a write the project's rules hold back answers 403 with retry: "after_approval" and an approval id; the agent resends with X-CLI-Approval: <id> once a person approves.

8. Payments

Hosts on the payments level take credit over x402 version 2:

  1. The agent calls POST /v1/projects/:id/topup?amount=<micro-USDC>.
  2. The host answers 402 with a PAYMENT-REQUIRED header: base64 JSON with x402Version: 2 and accepts[], one option per network, each with network, asset, amount and payTo.
  3. The agent pays and resends with PAYMENT-SIGNATURE; the host settles and answers 200 with the new balance.

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 and digest.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 and invocationId (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:

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.