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#

CodeMeaning
0success (approve --wait approved, ask --wait answered, ...)
1unexpected error (a bug or an unclassified failure)
2usage error: bad arguments, or the request was rejected as invalid / not found / conflicting
3not authorised: missing, revoked or expired key, wrong scope, IP not allowed
4quota exceeded, plan required, or rate limited (after retries)
5network or server error (safe to retry)
10denied: the owner chose a non-approving action
11card 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.

OptionDescription
--jsonForce JSON output (automatic when stdout is not a TTY).
--quiet, -qPrint nothing on success (errors still go to stderr; the exit code carries the result).
--plainPrint 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-colorNo 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, -hShow help for the command.
--version, -vPrint 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.

Verifies the key against the API, then writes ~/.config/agentsframe/config.json with mode 600. AGENTSFRAME_KEY / AGENTSFRAME_API override the file.

sh
frame login [options]

Options

OptionDescription
--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-verifyStore without calling the API.

Examples

sh
frame login --key afk_w_3fa9...
frame login --key afk_w_3fa9... --api http://127.0.0.1:8787/v1

Output (no key needed)

{"ok":true,"api","key_prefix","scope","account":{"id","name","plan"},"config_path"}

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame whoami#

Show the account and the key this CLI is using.

sh
frame whoami

Examples

sh
frame whoami

Output (needs a key)

{"account":{...},"key":{id,name,scope,prefix...},"api","key_source"}

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame doctor#

Check config, reachability, key scope and clock skew.

sh
frame doctor

Examples

sh
frame doctor

Output (no key needed)

{"ok":bool,"checks":[{"name","ok","detail"}]}

json
{
  "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

CodeMeaning
0success
1a check failed (e.g. clock skew)
2usage error
3key missing or rejected
4quota exceeded, plan required or rate limited
5API 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.

sh
frame approve <title> [options]

Arguments

NameDescription
titleWhat needs approval, 1..120 chars. The lock screen shows only this.

Options

OptionDescription
--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-unlockAnswering needs Face ID / Touch ID.
`--priority <lownormal
--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.
--waitBlock until answered, expired or --timeout (default).
--no-waitCreate the card and return immediately; collect later with frame card wait <id>.

Examples

sh
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-wait

Output (needs a key)

{"approved":bool,"outcome":"answered|expired|timeout|withdrawn","action","comment","by":{kind,name},"state","card_id","url"}

json
{
  "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

CodeMeaning
0approved
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)
10denied (the owner chose a non-approving action)
11card 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).

sh
frame ask <question> [options]

Arguments

NameDescription
questionThe question (card title, 1..120 chars).

Options

OptionDescription
--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[:optid=Label]>` (repeatable)
`--priority <lownormal
--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.
--waitBlock until answered, expired or --timeout (default).
--no-waitCreate the card and return immediately; collect later with frame card wait <id>.

Examples

sh
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"}

json
{
  "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

CodeMeaning
0answered
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)
11card 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).

sh
frame show <target> [options]

Arguments

NameDescription
targetFile path, directory path or http(s) URL.

Options

OptionDescription
--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.
--reviewAsk for sign-off: Looks good / Request changes, and wait.
--dry-runUpload nothing, create nothing: print what would be uploaded.
--max-bytes <bytes>Total upload cap for a folder (default 209715200 = 200 MB).
`--priority <lownormal
--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-waitCreate the card and return immediately; collect later with frame card wait <id>.

Examples

sh
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.pdf

Output (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"}

json
{
  "card_id": "crd_8f2a1c",
  "url": "https://app.agentsframe.com/c/crd_8f2a1c",
  "state": "open",
  "kind": "folder",
  "uploaded": 4,
  "bytes": 5120
}

Exit codes

CodeMeaning
0shown / looks good
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)
10changes requested
11review 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.

sh
frame progress start <title> [options]

Arguments

NameDescription
titleWhat is running.

Options

OptionDescription
--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.
--cancellableShow 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

sh
ID=$(frame progress start "Rendering video" --steps Extract,Encode,Upload --plain)

Output (needs a key)

{"card_id","url","state"}

json
{
  "card_id": "crd_8f2a1c",
  "url": "https://app.agentsframe.com/c/crd_8f2a1c",
  "state": "open"
}

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame progress update#

Update a status card: value, label, step done.

sh
frame progress update <id> [options]

Arguments

NameDescription
idCard id from progress start.

Options

OptionDescription
--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

sh
frame progress update crd_abc --value 0.4 --label 'Encoding 2/5' --step-done Extract

Output (needs a key)

{"card_id","url","state","progress":{...}}

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame progress done#

Finish a status card as succeeded and close it.

sh
frame progress done <id> [options]

Arguments

NameDescription
idCard id.

Options

OptionDescription
--label <text>Final status line.

Examples

sh
frame progress done crd_abc --label 'Uploaded'

Output (needs a key)

{"card_id","url","state","progress"}

json
{
  "card_id": "crd_8f2a1c",
  "url": "https://app.agentsframe.com/c/crd_8f2a1c",
  "state": "done",
  "progress": {
    "state": "succeeded",
    "value": 1,
    "label": "Uploaded"
  }
}

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame progress fail#

Finish a status card as failed and close it.

sh
frame progress fail <id> [options]

Arguments

NameDescription
idCard id.

Options

OptionDescription
--label <text>Final status line.

Examples

sh
frame progress fail crd_abc --label 'Encoder crashed'

Output (needs a key)

{"card_id","url","state","progress"}

json
{
  "card_id": "crd_8f2a1c",
  "url": "https://app.agentsframe.com/c/crd_8f2a1c",
  "state": "done",
  "progress": {
    "state": "failed",
    "label": "Encoder crashed"
  }
}

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame note#

Post a note card (no answer expected; read later in the inbox).

sh
frame note <text> [options]

Arguments

NameDescription
textMarkdown text; - reads stdin.

Options

OptionDescription
--title <text>Card title (default derived from the argument).
--class <dotted.class>Class for the owner's rules, e.g. deploy.production.
`--priority <lownormal
--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

sh
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"}

json
{
  "card_id": "crd_8f2a1c",
  "url": "https://app.agentsframe.com/c/crd_8f2a1c",
  "state": "open"
}

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame metric set#

Write one metric point (creates the metric on first write).

sh
frame metric set <name> <value> [options]

Arguments

NameDescription
name[a-z0-9][a-z0-9._-]{0,63}, e.g. youtube.subscribers.
valueNumber.

Options

OptionDescription
--label <text>Display name.
--unit <text>Unit, e.g. subs, ms, $.
`--format <numbercompact
--currency <ISO4217>With --format currency.
`--better <updown
--goal <n>Optional target.
--at <RFC3339>Timestamp of the point (default now).

Examples

sh
frame metric set youtube.subscribers 48210 --label Subscribers --format compact --better up

Output (needs a key)

Metric {name,label,value,previous,...}

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame metric get#

Read a metric, optionally with history points.

sh
frame metric get <name> [options]

Arguments

NameDescription
nameMetric name.

Options

OptionDescription
`--range <24h7d

Examples

sh
frame metric get youtube.subscribers --range 7d

Output (needs a key)

Metric {name,label,value,previous,points?}

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame metric list#

List all metrics with their latest values.

sh
frame metric list

Examples

sh
frame metric list

Output (needs a key)

Metric[]

json
[
  {
    "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame board list#

List boards (an account with none gets the default Home board).

sh
frame board list

Examples

sh
frame board list

Output (needs a key)

Board[]

json
[
  {
    "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame board get#

Read one board with its tiles.

sh
frame board get <id>

Arguments

NameDescription
idBoard id (brd_...).

Examples

sh
frame board get brd_home

Output (needs a key)

Board

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network 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.

sh
frame board put <id> <file>

Arguments

NameDescription
idBoard id.
filePath to the JSON file, or - for stdin.

Examples

sh
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

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame board tile#

Patch one tile of a board with a partial Tile (needs a board+ key).

sh
frame board tile <board> <tile> [options]

Arguments

NameDescription
boardBoard id.
tileTile id (til_...).

Options

OptionDescription
--json <'{...}'>Partial Tile as JSON. (Here --json carries the patch; machine output is automatic when piped.)
--data <'{...}'>Alias of --json for the patch.

Examples

sh
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

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame cards list#

List cards of this key's project, newest first.

sh
frame cards list [options]

Options

OptionDescription
--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

sh
frame cards list --state open
frame cards list --type approval --class 'deploy.*' --limit 5

Output (needs a key)

{"data":[Card...],"next_cursor":string|null}

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame card get#

Read one card including its response.

sh
frame card get <id>

Arguments

NameDescription
idCard id (crd_...).

Examples

sh
frame card get crd_abc123

Output (needs a key)

Card

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame card wait#

Wait for a card to be answered; exit code says how it ended.

sh
frame card wait <id>

Arguments

NameDescription
idCard id.

Examples

sh
frame card wait crd_abc123 --timeout 600

Output (needs a key)

{"outcome":"answered|expired|withdrawn|done|timeout","state","action","comment","by","values","card_id","url","card":{...}}

json
{
  "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

CodeMeaning
0answered positively / done / question answered
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)
10denied
11expired 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).

sh
frame card withdraw <id>

Arguments

NameDescription
idCard id.

Examples

sh
frame card withdraw crd_abc123

Output (needs a key)

{"card_id","withdrawn":true}

json
{
  "card_id": "crd_8f2a1c",
  "withdrawn": true
}

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame card respond#

Answer a card with a delegate key (only classes the key may answer; reason required).

sh
frame card respond <id> [options]

Arguments

NameDescription
idCard id.

Options

OptionDescription
--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

sh
frame card respond crd_abc --action approve --reason "Matches the standing release policy"

Output (needs a key)

Card

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame projects list#

List projects (admin key).

sh
frame projects list

Examples

sh
frame projects list

Output (needs a key)

Project[]

json
[
  {
    "id": "prj_demo",
    "name": "Default",
    "created_at": "2026-11-16T18:00:00.000Z"
  }
]

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame keys list#

List API keys of a project (admin key).

sh
frame keys list [options]

Options

OptionDescription
--project <prj_...>Project id (default: every project).

Examples

sh
frame keys list
frame keys list --project prj_abc

Output (needs a key)

ApiKey[] (no secrets)

json
[
  {
    "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame keys create#

Create an API key (admin key). The secret is shown once.

sh
frame keys create [options]

Options

OptionDescription
--name <text>Key name (shown on every card it posts). Required.
`--scope <writeboard
--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

sh
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)

json
{
  "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

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame keys revoke#

Revoke an API key (admin key).

sh
frame keys revoke <id>

Arguments

NameDescription
idKey id (key_...).

Examples

sh
frame keys revoke key_abc

Output (needs a key)

{"key_id","revoked":true}

json
{
  "key_id": "key_abc",
  "revoked": true
}

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network 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.

sh
frame webhook verify [options]

Options

OptionDescription
--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

sh
frame webhook verify --secret "$WEBHOOK_SECRET" --signature "$SIG" < body.json

Output (no key needed)

{"valid":bool,"timestamp","age_seconds","reason"?}

json
{
  "valid": true,
  "timestamp": 1763316000,
  "age_seconds": 2
}

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3signature invalid or stale (not authentic)
4quota exceeded, plan required or rate limited
5network 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.

sh
frame mcp

Examples

sh
claude mcp add agentsframe -- npx -y agentsframe mcp

Output (no key needed)

(speaks the MCP protocol on stdio; no JSON result)

json
"(speaks the MCP protocol on stdio; no JSON result)"

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)

frame commands#

Print every command with arguments, options and exit codes as JSON (for agents).

sh
frame commands [options]

Options

OptionDescription
--briefOnly names, usage lines and option names (about a quarter of the size).

Examples

sh
frame commands | jq '.commands[].name'
frame commands --brief

Output (no key needed)

{"name","version","exit_codes","global_options","commands":[{name,summary,args,options,examples,output,exits}]}

json
{
  "name": "frame",
  "version": "0.1.0",
  "exit_codes": {
    "0": "..."
  },
  "commands": [
    {
      "name": "approve",
      "summary": "...",
      "args": [],
      "options": []
    }
  ]
}

Exit codes

CodeMeaning
0success
1unexpected error
2usage error
3not authorised
4quota exceeded, plan required or rate limited
5network or server error (safe to retry)