stackbone contract

Every verb here targets a running agent installation and resolves it the standard way: the local-dev installation linked to the current project unless you pass --agent <installationId>. See target resolution. All three verbs are read-only, so none of them needs --yes. They accept --json and emit the usual { "schema_version": 1, ... } envelope.

Inspect the Stackbone Agent Protocol contract the targeted installation advertises, and validate the local project against it.

Command	Purpose
stackbone contract show	Print the full contract (version, build, runtime URL, capabilities).
stackbone contract capabilities	List the capabilities the installation reports (e.g. queues.jobs, storage.s3).
stackbone contract validate	Validate the local agent.yaml against the target's contract (or the local emulator contract when no installation is linked). Run it before you deploy.

capabilities comes from the same handshake show reads: there is no separate endpoint. validate fails (exit 1) when the contract version is unsupported or the target does not advertise a declared capability. Run it before you build an image and register it with stackbone link. There is no publish command: you host the workspace bundle yourself. See Going to production.

These three verbs report the installation-level contract: the protocol version and the capability strings the running box advertises. It carries no input/output schemas. A workspace agent declares its input/output contract per workflow, so the durable-workflow surface is the canonical view for schemas: use stackbone workflows schema <name> to read one workflow's input/output JSON Schema, and stackbone workflows list to see which workflows declare one.

Flags (all three verbs take the same one)

Flag	Type	Description
--agent <id>	string	Installation id to target. Defaults to the local-dev installation linked to this project.

stackbone contract show

Prints the handshake the targeted installation serves: the protocol version it speaks, the lowest version it still supports, the build that answered, the public runtime URL for this install (- when it reports none), and the capability list.

stackbone contract show
stackbone contract show --agent inst_123 --json

JSON payload

// contract show
{
  "schema_version": 1,
  "contract": {
    "version": 15,
    "minSupported": 1,
    // "stackbone-cli" (the local emulator) or "stackbone-api" (a deployed box)
    "build": { "name": "stackbone-cli", "version": "0.3.3" },
    "runtimeUrl": "https://example.invalid",
    "capabilities": ["database.postgres_direct", "storage.s3", "prompts.basic"],
  },
}

Only the per-install handshake populates runtimeUrl. It is null when the install has no reachable runtime (an offline local dev session). The local emulator contract omits the field.

stackbone contract capabilities

Lists the capability strings the installation reports, one per line, or No capabilities advertised. when the list is empty. It reads the same handshake as show (there is no separate endpoint). Use it when a script needs one fact without parsing the whole contract.

stackbone contract capabilities
stackbone contract capabilities --json

Capability membership is additive: a box may advertise a string this CLI has never heard of, and that is not an error.

JSON payload

// contract capabilities
{
  "schema_version": 1,
  "capabilities": [
    "database.postgres_direct",
    "rag.basic",
    "queues.jobs",
    "secrets.read_write",
    "config.read_write",
    "approval.fire_and_forget",
    "storage.s3",
    "ai.openrouter",
    "prompts.basic",
    "browser.provider",
  ],
}

That list is what the local emulator advertises. A deployed box advertises the subset its own build serves, so read the list rather than assuming it.

stackbone contract validate

Reads the agent.yaml in the current directory and checks it against the contract the target advertises. Two checks run: the contract version is still one this CLI can execute, and the contract advertises every capability the manifest declares.

stackbone contract validate
stackbone contract validate --agent inst_123 --json

validate reads the manifest first. agent.yaml is optional in a workspace and stackbone init does not write one, so run this verb only from a directory that has one. Without it the command exits 3 before it touches the network.

With a manifest in place, validate still works when nothing is linked yet: if there is no installation to resolve, it falls back to the local emulator contract instead of failing. The JSON source field says which contract it compared against, install or local-emulator. A linked project with no stackbone dev running is a different case. The CLI reports dev_not_running (also exit 3) instead of falling back.

The check is best-effort on the manifest side. The agent.yaml schema has no capabilities field and rejects unknown keys, so no manifest declares one: only the version check runs, and deviations records what the check skipped instead of failing the command. The CLI records an entry outside the protocol allowlist the same way, and never drops it.

JSON payload

// contract validate
{
  "schema_version": 1,
  "ok": true,
  "violations": [],
  // one line per manifest detail the check could not read, e.g.
  // "agent.yaml declares no `capabilities`"
  "deviations": [],
  "contractVersion": 15,
  "source": "install",
}

Exit codes: 0 ok · 3 no project (no agent.yaml, or the local-dev target has no stackbone dev running) · 1 generic (validation failed, contract incompatible). See exit codes.