@thesapientcompany/cli

Command-line interface for the Sapient brain-response API. Scan content, poll results, read your scan history, and query your cross-scan intelligence — all from your terminal.

Sapient predicts how a real human brain would respond to a piece of content (video, audio, image, or text) — second by second — and distills that into a score, a grade, and seven lenses.

Quick start

export SAPIENT_API_KEY=sk_live_…
npx @thesapientcompany/cli scan https://cdn.example.com/ad.mp4 --wait

Or install globally:

npm i -g @thesapientcompany/cli
sapient scan https://cdn.example.com/ad.mp4 --wait

Configuration

| Source | Description | | --- | --- | | SAPIENT_API_KEY env, or --key sk_live_… | Your API key. | | SAPIENT_BASE_URL env, or --base <url> | Override the API base URL (default https://www.thesapientcompany.com). |

Commands

sapient scan <url> [options]      Submit content; optionally wait for the result
sapient get <scan_id>             Fetch one scan
sapient history [--limit N]       List your scans
sapient intelligence [-q "..."]   Cross-scan patterns + semantic recall
sapient lenses                    List the 7 lenses

scan options

| Flag | Description | | --- | --- | | --model <m> | Model to scan with: mary (default) | qualia. See Models. | | --text "<copy>" | Scan raw text instead of a URL. (Pass - as the arg to read text from stdin.) | | --modality <m> | Hint for URL input: video | audio | image. | | --lenses a,b,c | Lenses to compute. Default top-3: attention,purchase_intent,manipulation. | | --reasons | Include per-second reasons + moments + summary. | | --raw | Include raw network values. | | --fmri | Include a signed fMRI artifact URL. | | --benchmark / --no-benchmark | Toggle benchmark percentiles (on by default). | | --no-reasons | Turn reasons off. | | --webhook <url> | POST the result to this URL on completion. | | --wait | Poll until the scan completes, then pretty-print the timeline/moments/summary. | | --timeout <sec> | Max seconds to wait with --wait (default 300). |

Global flags

--key, --base, --json (raw JSON output), -h/--help, -v/--version.

Models — Mary vs Qualia

Every scan runs on one of two models. The output shape is identical (same score, grade, seven lenses, per-second timeline) — what differs is what each reads and what it costs. Use --model to choose; omit it to default to Mary.

| Model | Price | Reads | Use it for | | --- | --- | --- | --- | | mary (default) | $0.50 / scan | Video, audio, voice, narrative, and text | The generalist for any content. Text, mixed media, or when you're unsure. | | qualia | $1.00 / scan | Video (visual + audio), no text | The visual specialist — sharper at telling visually-distinct video apart. Comparing video creatives. |

Decision rule: Text or mixed → Mary. Comparing videos → Qualia.

# Compare two video creatives with the visual specialist
sapient scan https://cdn.example.com/ad-a.mp4 --model qualia --wait
sapient scan https://cdn.example.com/ad-b.mp4 --model qualia --wait

The 7 lenses

attention, purchase_intent, manipulation, emotion, cognitive_effort, memory, surprise. Default top-3: attention, purchase_intent, manipulation.

Examples

# Submit a video and wait for the full result
sapient scan https://cdn.example.com/ad.mp4 --wait

# Scan copy under specific lenses
sapient scan --text "Buy now and save 50%" --lenses purchase_intent,manipulation --wait

# Pipe text in
echo "Limited time offer" | sapient scan - --wait

# Fetch a prior scan as raw JSON
sapient get mary_run_abc123 --json

# Your history and cross-scan intelligence
sapient history --limit 10
sapient intelligence -q "where do my ads lose attention?"

Errors

• 401 → set a valid sk_live_ key (SAPIENT_API_KEY or --key).
• 402 → out of credits; add API credits in Settings → API.
• 403 → a paid plan is required to use the API.
• 404 → no such scan, or it isn't yours.
• 429 → rate limited; retry with backoff.

Build from source

npm install
npm run build   # tsc → dist/

License

MIT