@scopeful/cli

Terminal interface to the Scopeful pricing engine. Interactive REPL with / commands, or one-shot JSON for agents.

Every command hits https://www.scopeful.org/api/mcp with the SCOPEFUL_API_KEY env var for auth + usage tracking. Add --json to any data command for raw JSON output (for agent subprocess use).

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

Two modes

1. Interactive REPL (humans)

Type scopeful with no arguments to open a guided session:

scopeful

Scopeful CLI v1.4.0
AI pricing intelligence in your terminal

  /help            show all commands
  /tools [search]  browse AI tools  (e.g. /tools flux)
  /models [search] browse AI models  (e.g. /models nano)
  /search <query>  search tools + models at once
  /recommend       find the cheapest option for a goal
  /calculate       exact cost for a model + volume
  /compare         side-by-side tool pricing
  /usage           your MCP usage this month
  /quit            exit

  Tip: type / to see all commands with autocomplete, Tab to complete.

Or type a keyword: image, video, cheapest, compare...

scopeful> /tools --category image

─── Tools (image) ───

  #  TOOL                SLUG                CATEGORIES  ACCESS  PRICING        FREE  FROM $/MO
  ─  ────                ────                ──────────  ──────  ───────        ────  ─────────
  1  Adobe Firefly       adobe-firefly       image       ui      hybrid          no      $9.99
  2  Black Forest Labs   flux                image       api     pay_per_use     no      $0.01
  3  Dreamina            dreamina            image, video ui      credits        yes     $14.54
  ...

20 tools in image. Type a number for details, or /tools --category <cat> to filter.

scopeful> 2

─── Black Forest Labs (flux) ───

  Categories       image
  Pricing          pay_per_use
  Access           api
  Free tier        no
  Last updated     2026-06-25

  api (api)
    economy: pay_per_use · access: api

    Models:
    MODEL             TYPE  RESOLUTION  PRICE
    ─────             ────  ──────────  ─────
    FLUX.1 [pro]      image 1K          $0.05/gen
    FLUX.1 [pro]      image 2K          $0.07/gen
    ...

Try: /calculate flux-pro 500 api to see exact pricing for your volume.

The REPL supports:

• / commands for navigation (/help for the full list)
• Numbered selections from the last list (type 3 to see details for item 3)
• Guided flows (/recommend, /calculate, /compare) that walk you through the inputs
• Keyword matching — type cheapest, compare, image, etc. and the REPL figures out what you want
• /json to re-print the last result as raw JSON
• Ctrl+C to cancel a prompt, Ctrl+D to exit

2. One-shot commands (agents)

For automation and agent subprocess use:

scopeful recommend image api 2000 --budget 50
scopeful calculate flux-pro 100 api 2K
scopeful list-tools --category image --limit 5
scopeful list-models --type image --kind generation
scopeful compare flux-pro fal replicate 500 api
scopeful get-tool midjourney
scopeful retrieve-workflow "real estate video pipeline"
scopeful team-workflows "thumbnail generator"
scopeful usage

All data commands output pretty tables by default. Add --json for raw JSON:

scopeful list-tools --json
scopeful usage --json

Install + configure

npm install -g @scopeful/cli

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

scopeful login sk_live_your_api_key_here

…or set it in the environment:

export SCOPEFUL_API_KEY=sk_live_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_live_... or scopeful login --key sk_live_... or echo "sk_live_..." \| 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.

Data

All data commands output pretty tables by default. Add --json for raw JSON (for agent subprocess use).

| 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 the same model across tools | scopeful compare <model-slug> <tool1> <tool2> [tool3] <qty> <access> | | 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 | | 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 | | --provider | list-models | Provider name substring | | --limit N | list-tools, list-models | 1-50, default 20 | | --resolution | compare | 1K, 2K, 3K, 4K, 480p, 540p, 720p, 1080p | | --json | all data commands | Output raw JSON instead of pretty tables |

Examples

# Interactive — opens the REPL
scopeful

# 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 FLUX.1 [pro] images at 2K via the API
scopeful calculate flux-pro 100 api 2K

# Browse image tools with a table
scopeful list-tools --category image

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

# Compare FLUX.1 [pro] pricing across fal.ai and Replicate for 500 images
scopeful compare flux-pro fal replicate 500 api

# Deep-dive on Midjourney
scopeful get-tool midjourney

# Raw JSON for an agent subprocess
scopeful list-tools --json

Subprocess invocation pattern (for agents)

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 --json", {
    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://app.scopeful.org/keys. | | SCOPEFUL_MCP_URL | No | https://www.scopeful.org/api/mcp | Override the upstream endpoint. Useful for local development. | | NO_COLOR | No | — | When set, disables ANSI colors in the output. |

Requirements

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

License

MIT