appshots

Generate App Store and Google Play screenshot sets from real app screens, straight from the terminal. Built for AI agents as much as for humans: non-interactive by default, JSON output when piped, typed exit codes, and errors that say what to run next.

npm install -g @revoks/appshots   # or: bunx @revoks/appshots / npx @revoks/appshots

Authenticate

First match wins:

1. APPSHOTS_API_KEY — an API key (appshots_…) created in Settings → API keys. Best for CI and agents.
2. APPSHOTS_TOKEN — a session token, sent as a bearer token.
3. A stored login from appshots login — a browser device flow (RFC 8628); the session token lands in ~/.config/appshots/credentials.json (0600).

Generate

appshots create \
  --app "Litewait" \
  --prompt "Queue tracking for busy clinics" \
  --style clean-minimal \
  --download ./store-shots \
  home.png stats.png queue.png

create uploads the screenshots, charges one credit per frame, waits for the set to render, and exits non-zero if it fails. appshots styles lists the built-in styles; --custom-style "…" describes your own.

Commands

| Command | What it does | | --- | --- | | login / logout / whoami | Device-flow sign-in, revoke, inspect the credential | | credits [--ledger] | Balance, generation costs, recent activity | | styles | The built-in visual styles | | create <screenshots…> | Upload sources and generate a set | | list / get <set-id> | Browse sets, inspect one | | wait <set-id> | Block until a set settles | | download <set-id> | Save the finished frames | | add-frame <set-id> | Extend a set by one frame | | refine <set-id> <frame-id> | Re-render one frame with feedback (also retries failures) | | cancel <set-id> | Stop a running set (unfinished frames refunded) | | delete <set-id> --yes | Permanently delete a set |

Run appshots <command> --help for flags and examples.

For scripts and agents

• stdout carries the result; progress and errors go to stderr.
• Output is JSON whenever stdout is piped, or always with --json.
• Exit codes: 0 success, 1 failure, 2 usage error, 3 authentication, 4 out of credits or no subscription.
• No prompts, no spinners, no pager. NO_COLOR and FORCE_COLOR are honored.
• APPSHOTS_API_URL overrides the API origin; APPSHOTS_CONFIG_DIR moves the config directory.
• An agent skill that teaches this CLI lives at appshots.me/skill.md — install it with npx skills add https://appshots.me, or save it manually as .claude/skills/appshots/SKILL.md (or your agent's equivalent).

The HTTP API behind the CLI is documented at appshots.me/api/reference.