@scopeful/cli

@scopeful/cli

Terminal interface to the Scopeful pricing engine. Subprocess-friendly for agents that don't speak MCP over STDIO but can run shell commands.

Every command posts to https://www.scopeful.org/api/mcp with the SCOPEFUL_API_KEY env var for auth and usage tracking, and writes JSON to stdout. Parse it with JSON.parse().

For STDIO MCP integration, install @scopeful/mcp instead. Both packages hit the same endpoint, use the same key, and are tracked identically.

Install + configure

npm install -g @scopeful/cli

Generate an API key at https://scopeful.org/pro/api, then either store it (recommended):

scopeful login sk_mcp_your_api_key_here

…or set it in the environment:

export SCOPEFUL_API_KEY=sk_mcp_your_api_key_here

SCOPEFUL_API_KEY always wins over the stored key.

Command reference

Auth

Goal	Command
Store an API key (interactive)	scopeful login
Store an API key (non-interactive)	scopeful login sk_mcp_... or scopeful login --key sk_mcp_... or echo "sk_mcp_..." | scopeful login
Remove stored credentials	scopeful logout
Show the active key (masked)	scopeful whoami
Show auth + setup state	scopeful status

scopeful login validates the key against the Scopeful API before saving it. The key is stored in ~/.scopeful/credentials.json with mode 0600 (POSIX) — Windows uses inherited ACLs. The SCOPEFUL_API_KEY env var always overrides the stored key.

Data

All data commands output JSON on stdout. Every response has the shape { "data": ..., "meta": { "staleness_days": N, "source": "supabase" } }.

Goal	Command
Discover tools for a goal	scopeful recommend <output-type> <access-type> <volume>
Price a specific model	scopeful calculate <model-slug> <quantity> <access-type>
Browse the tool catalog	scopeful list-tools [--category image|video|music]
Browse the model catalog	scopeful list-models [--type image|video|music] [--kind generation|upscale|edit|voice]
Compare 2-3 tools	scopeful compare <slug1> <slug2> [slug3] <quantity> <access-type>
Deep-dive on one tool	scopeful get-tool <slug>
Search for a workflow	scopeful retrieve-workflow <query>
Search team workflows	scopeful team-workflows <query> (requires team-scoped API key)
Show MCP usage for the current month	scopeful usage (or scopeful usage --json)
Install the agent skill	scopeful setup

Flags

Flag	Applies to	Values
--budget N	recommend	Max monthly USD
--billing	recommend, calculate	monthly (default), annual
--category	list-tools	image, video, music
--type	list-models	image, video, music
--kind	list-models	generation, upscale, edit, voice
--limit N	list-tools, list-models	1-50, default 20

Examples

# Discovery: rank options for an app builder needing 2000 monthly image gens
scopeful recommend image api 2000 --budget 50 --billing annual

# Exact cost for 100 Nano Banana 2 images at 2K via the UI
scopeful calculate nano-banana-2 100 ui 2K

# Browse image models
scopeful list-models --type image --kind generation

# Side-by-side pricing for 500 generations
scopeful compare midjourney kling leonardo 500 ui

Subprocess invocation pattern

Run commands with the API key in the environment. Parse stdout as JSON:

const { execSync } = require("child_process");
const result = JSON.parse(
  execSync("scopeful recommend image api 2000 --budget 50", {
    env: { ...process.env, SCOPEFUL_API_KEY: "sk_live_..." },
  }).toString(),
);
// result.data: ranked recommendations
// result.meta: staleness_days, source

Install the agent skill (optional)

scopeful setup

Drops the scopeful-cli skill into ~/.agents/skills/, ~/.claude/skills/, and ~/.cursor/skills/. Restart your agent to pick it up.

MCP vs CLI

Agent capability	Use
Speaks MCP over STDIO (Claude Desktop, Cursor, Windsurf, Antigravity, Cline)	@scopeful/mcp — faster, no shell parsing.
Shell/subprocess only	@scopeful/cli — scopeful subcommands with JSON stdout.

Both hit the same endpoint with the same key. Pick based on the agent's capabilities, not the task.

Environment variables

Variable	Required	Default	Notes
SCOPEFUL_API_KEY	Yes	—	Bearer token for https://www.scopeful.org/api/mcp. Every call is tracked to this key. Create one at https://scopeful.org/pro/api.
SCOPEFUL_MCP_URL	No	https://www.scopeful.org/api/mcp	Override the upstream endpoint. Useful for local development.

Requirements

• Node.js >=18 (declared in engines).

License

MIT