frame CLI reference#
Generated from the command registry (pnpm docs:cli); do not edit by hand. Version 0.1.0.
frame is built for scripts and AI agents. Output is one JSON document on stdout when stdout is not a TTY (or with --json); errors are JSON {"error":{"code","message","hint"}} on stderr. frame commands prints this whole reference as JSON.
Exit codes#
| Code | Meaning |
|---|---|
| 0 | success (approve --wait approved, ask --wait answered, ...) |
| 1 | unexpected error (a bug or an unclassified failure) |
| 2 | usage error: bad arguments, or the request was rejected as invalid / not found / conflicting |
| 3 | not authorised: missing, revoked or expired key, wrong scope, IP not allowed |
| 4 | quota exceeded, plan required, or rate limited (after retries) |
| 5 | network or server error (safe to retry) |
| 10 | denied: the owner chose a non-approving action |
| 11 | card expired or was withdrawn before an answer |
| 12 | --timeout reached while the card is still open (the card stays open) |
Global options#
Accepted by every command.
| Option | Description |
|---|---|
--json | Force JSON output (automatic when stdout is not a TTY). |
--quiet, -q | Print nothing on success (errors still go to stderr; the exit code carries the result). |
--plain | Print only the main value (a card id, an answer, a secret) instead of the JSON document. |
--timeout <seconds> | Seconds to wait for the owner in blocking commands (default 3600; also the card's time to live, min 60). For other commands: per-request timeout. |
--no-color | No ANSI colours (also honours the NO_COLOR environment variable; the CLI currently emits none). |
--api <url> | API base URL for this call (overrides AGENTSFRAME_API and the config file). |
--key <key> | API key for this call (overrides AGENTSFRAME_KEY and the config file). |
--help, -h | Show help for the command. |
--version, -v | Print the version. |
Environment: AGENTSFRAME_KEY (API key (overrides the config file)), AGENTSFRAME_API (API base URL), AGENTSFRAME_CONFIG (config file path), AGENTSFRAME_AGENT (source.agent on created cards (default frame-cli)). Precedence for the key and API URL: flag, environment, config file (~/.config/agentsframe/config.json), default.
Commands#
frame login: Store an API key (and optionally the API URL) in the config file.frame whoami: Show the account and the key this CLI is using.frame doctor: Check config, reachability, key scope and clock skew.frame approve: Ask the owner to approve or deny something; blocks until answered.frame ask: Ask the owner a question (choices or form fields); blocks until answered.frame show: Show the owner a file, folder or URL as a preview card.frame progress start: Create a status card with a progress bar; prints its id.frame progress update: Update a status card: value, label, step done.frame progress done: Finish a status card as succeeded and close it.frame progress fail: Finish a status card as failed and close it.frame note: Post a note card (no answer expected; read later in the inbox).frame metric set: Write one metric point (creates the metric on first write).frame metric get: Read a metric, optionally with history points.frame metric list: List all metrics with their latest values.frame board list: List boards (an account with none gets the default Home board).frame board get: Read one board with its tiles.frame board put: Replace a board's name, icon and tiles from a JSON file (needs a board+ key).frame board tile: Patch one tile of a board with a partial Tile (needs a board+ key).frame cards list: List cards of this key's project, newest first.frame card get: Read one card including its response.frame card wait: Wait for a card to be answered; exit code says how it ended.frame card withdraw: Withdraw your own open card (it disappears from the owner's inbox).frame card respond: Answer a card with a delegate key (only classes the key may answer; reason required).frame projects list: List projects (admin key).frame keys list: List API keys of a project (admin key).frame keys create: Create an API key (admin key). The secret is shown once.frame keys revoke: Revoke an API key (admin key).frame webhook verify: Verify a Frame-Signature header against a request body read from stdin.frame mcp: Run the MCP server on stdio (tools: ask_human, request_approval, show_result, ...).frame commands: Print every command with arguments, options and exit codes as JSON (for agents).
frame login#
Store an API key (and optionally the API URL) in the config file.
Verifies the key against the API, then writes ~/.config/agentsframe/config.json with mode 600. AGENTSFRAME_KEY / AGENTSFRAME_API override the file.
frame login [options]Options
| Option | Description |
|---|---|
--key <afk_...> | The API key (create one in the app: Settings > Keys). Required. |
--api <url> | API base URL (default https://api.agentsframe.com/v1). |
--no-verify | Store without calling the API. |
Examples
frame login --key afk_w_3fa9...
frame login --key afk_w_3fa9... --api http://127.0.0.1:8787/v1Output (no key needed)
{"ok":true,"api","key_prefix","scope","account":{"id","name","plan"},"config_path"}
{
"ok": true,
"api": "https://api.agentsframe.com/v1",
"key_prefix": "afk_w_3fa9",
"scope": "write",
"account": {
"id": "acc_demo",
"name": "Demo",
"plan": "pro"
},
"config_path": "/home/me/.config/agentsframe/config.json"
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame whoami#
Show the account and the key this CLI is using.
frame whoamiExamples
frame whoamiOutput (needs a key)
{"account":{...},"key":{id,name,scope,prefix...},"api","key_source"}
{
"account": {
"id": "acc_demo",
"name": "Demo",
"plan": "pro",
"limits": {
"cards_per_month": 20000
}
},
"key": {
"id": "key_abc",
"project_id": "prj_demo",
"name": "CI",
"scope": "write",
"prefix": "afk_w_3fa9",
"created_at": "2026-11-16T18:00:00.000Z"
},
"api": "https://api.agentsframe.com/v1",
"key_source": "env"
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame doctor#
Check config, reachability, key scope and clock skew.
frame doctorExamples
frame doctorOutput (no key needed)
{"ok":bool,"checks":[{"name","ok","detail"}]}
{
"ok": true,
"checks": [
{
"name": "config",
"ok": true,
"detail": "key from env, api https://api.agentsframe.com/v1 from default"
},
{
"name": "reachable",
"ok": true,
"detail": "answered in 84 ms"
},
{
"name": "key",
"ok": true,
"detail": "CI [write] afk_w_3fa9"
},
{
"name": "clock",
"ok": true,
"detail": "local clock is ahead by 1 s"
}
]
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | a check failed (e.g. clock skew) |
| 2 | usage error |
| 3 | key missing or rejected |
| 4 | quota exceeded, plan required or rate limited |
| 5 | API unreachable |
frame approve#
Ask the owner to approve or deny something; blocks until answered.
Creates an approval card and (by default) waits. Exit 0 = approved, 10 = denied, 11 = expired or withdrawn, 12 = --timeout reached (card stays open). Use --no-wait to only create the card.
frame approve <title> [options]Arguments
| Name | Description |
|---|---|
title | What needs approval, 1..120 chars. The lock screen shows only this. |
Options
| Option | Description |
|---|---|
--body <markdown> | Card body in markdown (<= 20000 chars). - reads stdin. |
--body-file <path> | Read the body from a file (- = stdin). |
--class <dotted.class> | Class for the owner's rules, e.g. deploy.production. |
--action <id:label[:style[:input]]> (repeatable) | Custom action (repeatable, max 4). Default Approve / Deny. The approve id or the primary one counts as approval. |
| `--on-expire <none | |
--require-unlock | Answering needs Face ID / Touch ID. |
| `--priority <low | normal |
--tag <tag> (repeatable) | Tag (repeatable, max 10). |
--thread <key> | Group key: cards with the same thread stack together. |
--dedupe-key <key> | Update the open card with this key instead of creating another. |
--wait | Block until answered, expired or --timeout (default). |
--no-wait | Create the card and return immediately; collect later with frame card wait <id>. |
Examples
frame approve "Deploy v2.3.1 to production?" --body "212 tests passed" --class deploy.production --timeout 900 --on-expire deny
frame approve "Delete 40 old branches?" --action approve:Delete:destructive --action keep:Keep --no-waitOutput (needs a key)
{"approved":bool,"outcome":"answered|expired|timeout|withdrawn","action","comment","by":{kind,name},"state","card_id","url"}
{
"approved": true,
"outcome": "answered",
"state": "answered",
"card_id": "crd_8f2a1c",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"action": "approve",
"comment": "ship it",
"by": {
"kind": "user",
"name": "Leo's iPhone"
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | approved |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
| 10 | denied (the owner chose a non-approving action) |
| 11 | card expired or was withdrawn before an answer |
| 12 | --timeout reached while the card is still open (it stays open) |
frame ask#
Ask the owner a question (choices or form fields); blocks until answered.
With --option a choice question; with --field a form; with neither a free-text answer. Exit 0 = answered, 11 = expired or withdrawn, 12 = --timeout reached (card stays open).
frame ask <question> [options]Arguments
| Name | Description |
|---|---|
question | The question (card title, 1..120 chars). |
Options
| Option | Description |
|---|---|
--body <markdown> | Card body in markdown (<= 20000 chars). - reads stdin. |
--body-file <path> | Read the body from a file (- = stdin). |
--class <dotted.class> | Class for the owner's rules, e.g. deploy.production. |
--option <id:label> (repeatable) | A choice for the single-choice shorthand (repeatable, 2..12). Answer is answer. |
| `--field <kind[*]:id:label[:opt | id=Label]>` (repeatable) |
| `--priority <low | normal |
--tag <tag> (repeatable) | Tag (repeatable, max 10). |
--thread <key> | Group key: cards with the same thread stack together. |
--dedupe-key <key> | Update the open card with this key instead of creating another. |
--wait | Block until answered, expired or --timeout (default). |
--no-wait | Create the card and return immediately; collect later with frame card wait <id>. |
Examples
frame ask "Which thumbnail?" --option a:"Bold title" --option b:"Face close-up"
frame ask "Release details" --field text*:version:Version --field toggle:notify:Notify subscribers
frame ask "Anything to add before I publish?"Output (needs a key)
{"outcome":"answered|expired|timeout","answer"?,"values":{id:value},"comment","by","state","card_id","url"}
{
"answered": true,
"answer": "b",
"outcome": "answered",
"state": "answered",
"card_id": "crd_8f2a1c",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"action": "submit",
"values": {
"answer": "b"
},
"by": {
"kind": "user",
"name": "Leo's iPhone"
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | answered |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
| 11 | card expired or was withdrawn before an answer |
| 12 | --timeout reached while the card is still open (it stays open) |
frame show#
Show the owner a file, folder or URL as a preview card.
Local files are uploaded (PUT /media) and shown with the right viewer by extension. A directory becomes a folder preview with nested items (skips dotfiles, node_modules; max 500 items, depth 4). A URL is shown as is. --review adds Looks good / Request changes and waits (exit 0 / 10 / 11 / 12).
frame show <target> [options]Arguments
| Name | Description |
|---|---|
target | File path, directory path or http(s) URL. |
Options
| Option | Description |
|---|---|
--title <text> | Card title (default derived from the argument). |
--body <markdown> | Card body in markdown (<= 20000 chars). - reads stdin. |
--body-file <path> | Read the body from a file (- = stdin). |
--class <dotted.class> | Class for the owner's rules, e.g. deploy.production. |
--review | Ask for sign-off: Looks good / Request changes, and wait. |
--dry-run | Upload nothing, create nothing: print what would be uploaded. |
--max-bytes <bytes> | Total upload cap for a folder (default 209715200 = 200 MB). |
| `--priority <low | normal |
--tag <tag> (repeatable) | Tag (repeatable, max 10). |
--thread <key> | Group key: cards with the same thread stack together. |
--dedupe-key <key> | Update the open card with this key instead of creating another. |
--no-wait | Create the card and return immediately; collect later with frame card wait <id>. |
Examples
frame show ./out/demo.mp4 --title 'Render finished'
frame show ./brand-kit --review --body 'Final logos'
frame show ./dist --dry-run
frame show https://example.com/report.pdfOutput (needs a key)
{"card_id","url","state","kind","uploaded":n,"bytes":n} ; with --review also {"approved","outcome","action","comment","by"} ; with --dry-run {"dry_run":true,"files":[...],"total_bytes"}
{
"card_id": "crd_8f2a1c",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"state": "open",
"kind": "folder",
"uploaded": 4,
"bytes": 5120
}Exit codes
| Code | Meaning |
|---|---|
| 0 | shown / looks good |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
| 10 | changes requested |
| 11 | review expired or withdrawn |
| 12 | --timeout reached while the review is still open |
frame progress start#
Create a status card with a progress bar; prints its id.
frame progress start <title> [options]Arguments
| Name | Description |
|---|---|
title | What is running. |
Options
| Option | Description |
|---|---|
--steps <a,b,c> | Comma-separated step labels; the first starts active. |
--value <0..1> | Initial progress; omit for indeterminate. |
--label <text> | Status line, e.g. Rendering 3/8. |
--cancellable | Show a Cancel action to the owner. |
--body <markdown> | Card body in markdown (<= 20000 chars). - reads stdin. |
--class <dotted.class> | Class for the owner's rules, e.g. deploy.production. |
--tag <tag> (repeatable) | Tag (repeatable, max 10). |
--thread <key> | Group key: cards with the same thread stack together. |
--dedupe-key <key> | Update the open card with this key instead of creating another. |
Examples
ID=$(frame progress start "Rendering video" --steps Extract,Encode,Upload --plain)Output (needs a key)
{"card_id","url","state"}
{
"card_id": "crd_8f2a1c",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"state": "open"
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame progress update#
Update a status card: value, label, step done.
frame progress update <id> [options]Arguments
| Name | Description |
|---|---|
id | Card id from progress start. |
Options
| Option | Description |
|---|---|
--value <0..1> | Progress fraction. |
--label <text> | Status line. |
--step-done <label> (repeatable) | Mark a step done (repeatable); the next pending one becomes active. |
Examples
frame progress update crd_abc --value 0.4 --label 'Encoding 2/5' --step-done ExtractOutput (needs a key)
{"card_id","url","state","progress":{...}}
{
"card_id": "crd_8f2a1c",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"state": "open",
"progress": {
"state": "running",
"value": 0.4,
"label": "Encoding 2/5",
"steps": [
{
"label": "Extract",
"state": "done"
},
{
"label": "Encode",
"state": "active"
},
{
"label": "Upload",
"state": "pending"
}
]
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame progress done#
Finish a status card as succeeded and close it.
frame progress done <id> [options]Arguments
| Name | Description |
|---|---|
id | Card id. |
Options
| Option | Description |
|---|---|
--label <text> | Final status line. |
Examples
frame progress done crd_abc --label 'Uploaded'Output (needs a key)
{"card_id","url","state","progress"}
{
"card_id": "crd_8f2a1c",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"state": "done",
"progress": {
"state": "succeeded",
"value": 1,
"label": "Uploaded"
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame progress fail#
Finish a status card as failed and close it.
frame progress fail <id> [options]Arguments
| Name | Description |
|---|---|
id | Card id. |
Options
| Option | Description |
|---|---|
--label <text> | Final status line. |
Examples
frame progress fail crd_abc --label 'Encoder crashed'Output (needs a key)
{"card_id","url","state","progress"}
{
"card_id": "crd_8f2a1c",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"state": "done",
"progress": {
"state": "failed",
"label": "Encoder crashed"
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame note#
Post a note card (no answer expected; read later in the inbox).
frame note <text> [options]Arguments
| Name | Description |
|---|---|
text | Markdown text; - reads stdin. |
Options
| Option | Description |
|---|---|
--title <text> | Card title (default derived from the argument). |
--class <dotted.class> | Class for the owner's rules, e.g. deploy.production. |
| `--priority <low | normal |
--tag <tag> (repeatable) | Tag (repeatable, max 10). |
--thread <key> | Group key: cards with the same thread stack together. |
--dedupe-key <key> | Update the open card with this key instead of creating another. |
Examples
frame note "Nightly build finished: 212 passed" --title "Build"
git log -5 --oneline | frame note - --title 'Last commits'Output (needs a key)
{"card_id","url","state"}
{
"card_id": "crd_8f2a1c",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"state": "open"
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame metric set#
Write one metric point (creates the metric on first write).
frame metric set <name> <value> [options]Arguments
| Name | Description |
|---|---|
name | [a-z0-9][a-z0-9._-]{0,63}, e.g. youtube.subscribers. |
value | Number. |
Options
| Option | Description |
|---|---|
--label <text> | Display name. |
--unit <text> | Unit, e.g. subs, ms, $. |
| `--format <number | compact |
--currency <ISO4217> | With --format currency. |
| `--better <up | down |
--goal <n> | Optional target. |
--at <RFC3339> | Timestamp of the point (default now). |
Examples
frame metric set youtube.subscribers 48210 --label Subscribers --format compact --better upOutput (needs a key)
Metric {name,label,value,previous,...}
{
"name": "youtube.subscribers",
"label": "Subscribers",
"unit": "subs",
"format": "compact",
"value": 48210,
"previous": 47980,
"better": "up",
"goal": 50000,
"updated_at": "2026-11-16T18:00:00.000Z"
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame metric get#
Read a metric, optionally with history points.
frame metric get <name> [options]Arguments
| Name | Description |
|---|---|
name | Metric name. |
Options
| Option | Description |
|---|---|
| `--range <24h | 7d |
Examples
frame metric get youtube.subscribers --range 7dOutput (needs a key)
Metric {name,label,value,previous,points?}
{
"name": "youtube.subscribers",
"label": "Subscribers",
"unit": "subs",
"format": "compact",
"value": 48210,
"previous": 47980,
"better": "up",
"goal": 50000,
"updated_at": "2026-11-16T18:00:00.000Z",
"points": [
{
"at": "2026-11-15T18:00:00.000Z",
"value": 47980
},
{
"at": "2026-11-16T18:00:00.000Z",
"value": 48210
}
]
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame metric list#
List all metrics with their latest values.
frame metric listExamples
frame metric listOutput (needs a key)
Metric[]
[
{
"name": "youtube.subscribers",
"label": "Subscribers",
"unit": "subs",
"format": "compact",
"value": 48210,
"previous": 47980,
"better": "up",
"goal": 50000,
"updated_at": "2026-11-16T18:00:00.000Z"
}
]Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame board list#
List boards (an account with none gets the default Home board).
frame board listExamples
frame board listOutput (needs a key)
Board[]
[
{
"id": "brd_home",
"name": "Home",
"position": 0,
"tiles": [
{
"id": "til_a1",
"size": "medium",
"source": {
"kind": "metric",
"metric": "youtube.subscribers"
}
}
],
"updated_at": "2026-11-16T18:00:00.000Z",
"updated_by": {
"kind": "key",
"name": "CI"
}
}
]Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame board get#
Read one board with its tiles.
frame board get <id>Arguments
| Name | Description |
|---|---|
id | Board id (brd_...). |
Examples
frame board get brd_homeOutput (needs a key)
Board
{
"id": "brd_home",
"name": "Home",
"position": 0,
"tiles": [
{
"id": "til_a1",
"size": "medium",
"source": {
"kind": "metric",
"metric": "youtube.subscribers"
}
}
],
"updated_at": "2026-11-16T18:00:00.000Z",
"updated_by": {
"kind": "key",
"name": "CI"
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame board put#
Replace a board's name, icon and tiles from a JSON file (needs a board+ key).
The file is a BoardInput: {name, icon?, tiles:[{size, source, ...}]}. Tiles the owner pinned are kept by the server.
frame board put <id> <file>Arguments
| Name | Description |
|---|---|
id | Board id. |
file | Path to the JSON file, or - for stdin. |
Examples
frame board put brd_home ./home.json
frame board get brd_home | jq '.tiles |= map(select(.size!="small"))' | frame board put brd_home -Output (needs a key)
Board
{
"id": "brd_home",
"name": "Home",
"position": 0,
"tiles": [
{
"id": "til_a1",
"size": "medium",
"source": {
"kind": "metric",
"metric": "youtube.subscribers"
}
}
],
"updated_at": "2026-11-16T18:00:00.000Z",
"updated_by": {
"kind": "key",
"name": "CI"
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame board tile#
Patch one tile of a board with a partial Tile (needs a board+ key).
frame board tile <board> <tile> [options]Arguments
| Name | Description |
|---|---|
board | Board id. |
tile | Tile id (til_...). |
Options
| Option | Description |
|---|---|
--json <'{...}'> | Partial Tile as JSON. (Here --json carries the patch; machine output is automatic when piped.) |
--data <'{...}'> | Alias of --json for the patch. |
Examples
frame board tile brd_home til_a1 --json '{"title":"Subscribers","tint":"green"}'
frame board tile brd_home til_a1 --json '{"source":{"kind":"metric","metric":"youtube.subscribers"}}'Output (needs a key)
Board
{
"id": "brd_home",
"name": "Home",
"position": 0,
"tiles": [
{
"id": "til_a1",
"size": "medium",
"source": {
"kind": "metric",
"metric": "youtube.subscribers"
}
}
],
"updated_at": "2026-11-16T18:00:00.000Z",
"updated_by": {
"kind": "key",
"name": "CI"
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame cards list#
List cards of this key's project, newest first.
frame cards list [options]Options
| Option | Description |
|---|---|
--state <open,answered,...> | Comma list of states. |
--type <approval,question,...> | Comma list of types. |
--class <glob> | Class glob, e.g. deploy.* |
--tag <tag> | Tag filter. |
--thread <key> | Thread filter. |
--q <text> | Search title and body. |
--limit <n> | Max cards (<= 100, default 50). |
--cursor <cursor> | Page cursor from a previous next_cursor. |
Examples
frame cards list --state open
frame cards list --type approval --class 'deploy.*' --limit 5Output (needs a key)
{"data":[Card...],"next_cursor":string|null}
{
"data": [
{
"id": "crd_8f2a1c",
"type": "approval",
"title": "Deploy v2.3.1 to production?",
"priority": "normal",
"state": "open",
"class": "deploy.production",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"source": {
"agent": "frame-cli",
"key_name": "CI"
}
}
],
"next_cursor": null
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame card get#
Read one card including its response.
frame card get <id>Arguments
| Name | Description |
|---|---|
id | Card id (crd_...). |
Examples
frame card get crd_abc123Output (needs a key)
Card
{
"id": "crd_8f2a1c",
"type": "approval",
"title": "Deploy v2.3.1 to production?",
"priority": "normal",
"state": "open",
"class": "deploy.production",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"source": {
"agent": "frame-cli",
"key_name": "CI"
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame card wait#
Wait for a card to be answered; exit code says how it ended.
frame card wait <id>Arguments
| Name | Description |
|---|---|
id | Card id. |
Examples
frame card wait crd_abc123 --timeout 600Output (needs a key)
{"outcome":"answered|expired|withdrawn|done|timeout","state","action","comment","by","values","card_id","url","card":{...}}
{
"outcome": "answered",
"state": "answered",
"action": "approve",
"by": {
"kind": "user",
"name": "Leo's iPhone"
},
"card_id": "crd_8f2a1c",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"card": {
"id": "crd_8f2a1c",
"type": "approval",
"title": "Deploy v2.3.1 to production?",
"priority": "normal",
"state": "answered",
"class": "deploy.production",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"source": {
"agent": "frame-cli",
"key_name": "CI"
}
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | answered positively / done / question answered |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
| 10 | denied |
| 11 | expired or withdrawn |
| 12 | --timeout reached while the card is still open |
frame card withdraw#
Withdraw your own open card (it disappears from the owner's inbox).
frame card withdraw <id>Arguments
| Name | Description |
|---|---|
id | Card id. |
Examples
frame card withdraw crd_abc123Output (needs a key)
{"card_id","withdrawn":true}
{
"card_id": "crd_8f2a1c",
"withdrawn": true
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame card respond#
Answer a card with a delegate key (only classes the key may answer; reason required).
frame card respond <id> [options]Arguments
| Name | Description |
|---|---|
id | Card id. |
Options
| Option | Description |
|---|---|
--action <id> | Action id to take (required). |
--reason <text> | Why the agent answers; shown on the card (required for delegate keys). |
--comment <text> | Optional comment. |
Examples
frame card respond crd_abc --action approve --reason "Matches the standing release policy"Output (needs a key)
Card
{
"id": "crd_8f2a1c",
"type": "approval",
"title": "Deploy v2.3.1 to production?",
"priority": "normal",
"state": "answered",
"class": "deploy.production",
"url": "https://app.agentsframe.com/c/crd_8f2a1c",
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"source": {
"agent": "frame-cli",
"key_name": "CI"
},
"response": {
"action": "approve",
"by": {
"kind": "key",
"name": "release-bot"
},
"at": "2026-11-16T18:05:00.000Z"
}
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame projects list#
List projects (admin key).
frame projects listExamples
frame projects listOutput (needs a key)
Project[]
[
{
"id": "prj_demo",
"name": "Default",
"created_at": "2026-11-16T18:00:00.000Z"
}
]Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame keys list#
List API keys of a project (admin key).
frame keys list [options]Options
| Option | Description |
|---|---|
--project <prj_...> | Project id (default: every project). |
Examples
frame keys list
frame keys list --project prj_abcOutput (needs a key)
ApiKey[] (no secrets)
[
{
"id": "key_abc",
"project_id": "prj_demo",
"name": "CI",
"scope": "write",
"prefix": "afk_w_3fa9",
"created_at": "2026-11-16T18:00:00.000Z"
}
]Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame keys create#
Create an API key (admin key). The secret is shown once.
frame keys create [options]Options
| Option | Description |
|---|---|
--name <text> | Key name (shown on every card it posts). Required. |
| `--scope <write | board |
--project <prj_...> | Project id (default: the first project). |
--delegate-class <glob> (repeatable) | Class glob a delegate key may answer (repeatable). |
--allowed-ip <cidr> (repeatable) | Restrict to this CIDR (repeatable). |
--expires <RFC3339> | Expiry timestamp. |
Examples
frame keys create --name "CI" --scope write
frame keys create --name "Release bot" --scope delegate --delegate-class "deploy.staging.*"Output (needs a key)
CreatedKey (includes secret, shown once)
{
"id": "key_abc",
"project_id": "prj_demo",
"name": "CI",
"scope": "write",
"prefix": "afk_w_3fa9",
"created_at": "2026-11-16T18:00:00.000Z",
"secret": "afk_w_3fa9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8"
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame keys revoke#
Revoke an API key (admin key).
frame keys revoke <id>Arguments
| Name | Description |
|---|---|
id | Key id (key_...). |
Examples
frame keys revoke key_abcOutput (needs a key)
{"key_id","revoked":true}
{
"key_id": "key_abc",
"revoked": true
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame webhook verify#
Verify a Frame-Signature header against a request body read from stdin.
Receiver helper: t=<unix>,v1=<hex hmac_sha256(secret, t + "." + body)>. Exit 0 valid, 3 invalid.
frame webhook verify [options]Options
| Option | Description |
|---|---|
--secret <whsec...> | The project's webhook secret. Required. |
--signature <header> | The Frame-Signature header value. Required. |
--tolerance <seconds> | Max age of the timestamp. Default 300. |
Examples
frame webhook verify --secret "$WEBHOOK_SECRET" --signature "$SIG" < body.jsonOutput (no key needed)
{"valid":bool,"timestamp","age_seconds","reason"?}
{
"valid": true,
"timestamp": 1763316000,
"age_seconds": 2
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | signature invalid or stale (not authentic) |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame mcp#
Run the MCP server on stdio (tools: ask_human, request_approval, show_result, ...).
Reads the same config as the CLI. Add to an agent: claude mcp add agentsframe -- npx -y agentsframe mcp.
frame mcpExamples
claude mcp add agentsframe -- npx -y agentsframe mcpOutput (no key needed)
(speaks the MCP protocol on stdio; no JSON result)
"(speaks the MCP protocol on stdio; no JSON result)"Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |
frame commands#
Print every command with arguments, options and exit codes as JSON (for agents).
frame commands [options]Options
| Option | Description |
|---|---|
--brief | Only names, usage lines and option names (about a quarter of the size). |
Examples
frame commands | jq '.commands[].name'
frame commands --briefOutput (no key needed)
{"name","version","exit_codes","global_options","commands":[{name,summary,args,options,examples,output,exits}]}
{
"name": "frame",
"version": "0.1.0",
"exit_codes": {
"0": "..."
},
"commands": [
{
"name": "approve",
"summary": "...",
"args": [],
"options": []
}
]
}Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | not authorised |
| 4 | quota exceeded, plan required or rate limited |
| 5 | network or server error (safe to retry) |