The @surfable/cli package gives you full dashboard parity from your terminal — ingest sites, run searches, manage API keys, and configure your tenant without touching the UI. Useful for local development, CI/CD pipelines, and scripted ingest workflows.

Installation

npm install -g @surfable/cli
# or
pnpm add -g @surfable/cli

Requires Node.js 18+.

Authentication

surfable login

Prompts for your email and password. On success, stores a session token in your OS config directory (~/.config/surfable/ on Linux, ~/Library/Preferences/surfable/ on macOS). Run surfable logout to clear it.

surfable whoami      # print your tenant name, plan, and email
surfable logout      # clear all stored credentials

CI / Non-Interactive Usage

Set SURFABLE_API_KEY as an environment variable to skip interactive login entirely:

SURFABLE_API_KEY=sk_live_... surfable search "my query" --json

All commands support --json to output machine-readable JSON and suppress spinners/colours — suitable for piping into jq or CI log parsers.

Configuration

surfable config set api-url http://localhost:3001   # point at a local API instance
surfable config get                                  # print current config (key is redacted)

URL resolution order (highest wins): SURFABLE_API_URL env var → stored config → https://api.surfable.ai.

Commands

Sources (Ingest)

Manage the websites and documents indexed in your knowledge base.

surfable sources list
surfable sources add <url> [--max-depth N] [--max-pages N]
surfable sources status <sourceId>
surfable sources update <sourceId> [--max-depth N] [--max-pages N]
surfable sources recrawl <sourceId>
surfable sources delete <sourceId>

Shorthand aliases — ingest maps directly to sources:

surfable ingest https://yoursite.com          # same as sources add
surfable ingest list                           # same as sources list
surfable ingest status <sourceId>              # same as sources status
surfable ingest delete <sourceId>              # same as sources delete

Schedules

Set automatic recrawl schedules on any source.

surfable schedules set <sourceId> <frequency>   # hourly | daily | weekly | monthly | manual
surfable schedules clear <sourceId>              # remove schedule (resets to manual)

Current schedule is visible in surfable sources list.

Content

Browse and remove individual indexed content items.

surfable content list [--source <sourceId>]    # list indexed pages
surfable content delete <contentId>            # remove a specific item

Security (Blocklist)

Block URL patterns from being ingested.

surfable security list
surfable security block <pattern>      # e.g. "https://yoursite.com/private/*"
surfable security unblock <id>

Widget Routing (Watchtower)

Configure URL-pattern-based routing rules that customise the AI mode and system prompt per page.

surfable routes list
surfable routes add --pattern <glob> --mode <mode> [--prompt <text>] [--name <name>]
surfable routes update <id> [--pattern <glob>] [--mode <mode>] [--prompt <text>]
surfable routes delete <id>
surfable routes reorder     # interactive reorder

--mode values: search, rag, agent.

API Keys

surfable keys list
surfable keys create [--name <name>]           # prints key once — copy immediately
surfable keys revoke <id>
surfable keys suspend <id>
surfable keys unsuspend <id>

Search & Chat

Test your indexed content directly from the terminal.

surfable search "how do I get started" [--limit N] [--json]
surfable chat "what are the pricing options" [--session <id>]

surfable search uses POST /search and surfable chat uses POST /rag. Both accept an X-API-Key header — no session login required if SURFABLE_API_KEY is set.

Quota & Insights

surfable quota                               # current credits, search count, ingest count
surfable insights [--period 24h|7d|30d]      # usage over time
surfable insights top-queries [--period 7d]  # top search queries from your users

Settings

surfable settings show
surfable settings update [--name <name>] [--allowed-origins <origins>]

settings update requires admin credentials (your login session, not just an API key).

Exit Codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Error — safe to use in shell scripts with set -e |

Output Formats

By default all commands render formatted, human-readable output with colour and spinners.

Pass --json to any command to get structured JSON on stdout with no decoration — useful in CI, scripts, or when piping to other tools:

surfable sources list --json | jq '.[].url'
surfable quota --json | jq '.credits.remaining'

Environment Variables

| Variable | Description | |---|---| | SURFABLE_API_KEY | API key for non-interactive auth (overrides stored config) | | SURFABLE_API_URL | Override API base URL (overrides stored config) | | NO_COLOR | Disable all terminal colour output | | FORCE_COLOR | Force colour even when not in a TTY | | DEBUG | Print full stack traces on errors |

Next Steps

Quick Start — get up and running via the API directly
API Reference — the full endpoint surface the CLI wraps
Integrations — embed search and chat in your own UI
CLI Agent Skill — add this CLI to Claude, Cursor, or Copilot in one step