Quickstart#

Install the app, create a key, and have an agent ask you something. About 60 seconds.

1. Install the app#

Download Frame from the App Store on your iPhone, iPad or Mac and open it once. It creates your account on the device (no email needed) and asks to allow notifications. Say yes: that is how approvals reach your lock screen.

2. Create an API key#

In the app: Settings → Projects → Default → Keys → New key. Name it (for example my-laptop), choose the write scope, and copy the secret. It starts with afk_w_ and is shown once.

Keep the key out of git. Put it in an environment variable or your CI secret store.

3. Log in with the CLI#

bash
npx agentsframe login --key afk_w_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This verifies the key and stores it in ~/.config/agentsframe/config.json (permissions 600). To skip the file, export AGENTSFRAME_KEY instead. Check the connection any time:

bash
npx agentsframe whoami
npx agentsframe doctor

4. Send your first approval#

bash
npx agentsframe approve "Deploy?" --wait

Your phone buzzes with Deploy? and two buttons. The command waits until you tap, prints the result and exits with a code your script can branch on: 0 approved, 10 denied.

output (JSON when piped, or with --json)
{"approved":true,"outcome":"answered","action":"approve","state":"answered","card_id":"crd_8f2k1x"}

Use it in a script:

bash
if frame approve "Run the database migration on prod?" --wait --timeout 600 --on-expire deny; then
  ./migrate.sh
else
  echo "Not approved, skipping." >&2
fi

The same with curl#

No CLI needed. Create the card, then long-poll for the answer.

bash
export AGENTSFRAME_KEY=afk_w_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 1. create the card
CARD=$(curl -s https://api.agentsframe.com/v1/cards \
  -H "Authorization: Bearer $AGENTSFRAME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"approval","title":"Deploy?"}')
ID=$(echo "$CARD" | jq -r .id)

# 2. wait for the answer (returns 200 once answered, 202 while still open)
until [ "$(curl -s -o /tmp/card.json -w '%{http_code}' \
  -H "Authorization: Bearer $AGENTSFRAME_KEY" \
  "https://api.agentsframe.com/v1/cards/$ID/wait?timeout=50")" = 200 ]; do :; done

jq -r '.response.action' /tmp/card.json   # approve | deny

Without actions an approval gets Approve and Deny. wait is a long poll: it returns 200 with the card as soon as state leaves open, or 202 after timeout seconds (1 to 55) so you loop.

From code#

TypeScript
import { Frame } from "agentsframe";

const frame = new Frame({ key: process.env.AGENTSFRAME_KEY! });
const { approved } = await frame.approve("Deploy?", { wait: true });
if (approved) await deploy();
Python
from agentsframe import Frame

frame = Frame()  # reads AGENTSFRAME_KEY
if frame.approve("Deploy?", wait=True).approved:
    deploy()

What next#

  • Ask a question with choices: frame ask "Which thumbnail?" --option a:A --option b:B
  • Show a result: frame show ./render.mp4 --title "Episode 12" --review
  • Report progress: frame progress start "Nightly import" --value 0.6
  • Put a number on your board: frame metric set youtube.subscribers 48210
  • Give Claude Code or Codex a tool to reach you: MCP setup
  • Learn the model: Concepts