SarvCrawl / Docs /CLI

SarvCrawl CLI

Scrape, crawl, search, upload and manage knowledge bases straight from your terminal — a beautiful command line styled to match SarvCrawl, with live job spinners and clean tables.

npm install -g sarvcrawl-cli

The CLI installs two commands — sarv-kb and sarvcrawl. Both are identical; use whichever you prefer.

What is the SarvCrawl CLI?

A single binary that wraps the entire SarvCrawl backend. It is a thin layer over the sarvcrawl, so every endpoint the SDK supports is one command away.

sarv ▸ kb— zsh

$ sarv-kb scrape https://example.com --kb kb_abc123 --wait

✓ Job submitted job_xyz999 QUEUED

⠴ Job job_xyz999 RUNNING · 0 pages

Job job_xyz999 COMPLETED

Type scrape

Pages stored 3

✓ Job completed

Manage KBs

Create, list, inspect, and delete knowledge bases.

Ingest content

Scrape, crawl, web-search, map, or upload files.

Search & export

Full-text search, browse pages, export JSONL/ZIP.

Installation

Built the same way as the SDK and MCP packages — npm pack for local dev, then a global install.

Pack the CLI

From the repo: cd kb-backend/apps/cli, then npm install and npm pack. This produces sarv-kb-cli-1.0.0.tgz.

Install it globally

Run the install command below. It registers both sarv-kb and kb on your PATH.

Verify

Run sarv-kb --help — you should see the branded help screen.

npm install -g ./sarv-kb-cli-1.0.0.tgz

Prefer not to install globally? Run it in place with node bin/sarv-kb.js --help.

Authentication

The backend authenticates with an x-api-key. Log in once and it is stored in ~/.sarv-kb/config.json.

sarv ▸ kb— zsh

$ sarv-kb login

› Backend URL (https://crawl.sarv.com):

› API key: ••••••••••••

✓ Logged in successfully

Backend https://crawl.sarv.com

User admin@example.com

Or use environment variables

Resolution precedence is flag → env var → config file → default.

sarv ▸ kb— zsh

export KB_API_KEY=api-key

export KB_API_URL=https://crawl.sarv.com

sarv-kb login

Interactive, masked key prompt + validation.

sarv-kb config

Show config and where each value came from.

sarv-kb --status

Version, auth, and backend service health.

Health at a glance

sarv ▸ kb— zsh

$ sarv-kb --status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

sarv ▸ kb

the knowledge-base command line

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Authenticated via env

● Backend https://crawl.sarv.com

Services OK

✓ postgres ok

✓ redis ok

✓ rabbitmq ok

✓ minio ok

Command map

Everything the CLI can do, grouped by what you are trying to accomplish.

Authlogin · logout · config · status

KBskb create · kb list · kb get · kb stats · kb delete

Ingestscrape · crawl · search · map · upload

Jobsjobs · job (--wait --logs --audit --cancel --delete)

Retrievefind · pages · page

Filesfiles list · files download · files export-job · files export-kb · export

Knowledge bases

Create and inspect the containers your content lives in.

sarv ▸ kb— zsh

$ sarv-kb kb create "Docs KB" --description "Product docs"

✓ Created knowledge base Docs KB

ID kb_abc12345

$ sarv-kb kb list

┌─────────────┬───────────┬───────┬─────────┐

│ ID │ Name │ Pages │ Created │

├─────────────┼───────────┼───────┼─────────┤

│ kb_abc12345 │ Docs KB │ 42 │ 1d ago │

│ kb_def67890 │ Marketing │ 7 │ 2h ago │

└─────────────┴───────────┴───────┴─────────┘

2 knowledge bases

Ingestion jobs

Five ways to get content into a KB. Every command targets a KB with --kb and accepts --wait to poll to completion with a live spinner.

scrapesarv-kb scrape https://example.com --kb <id> --only-main-content --wait

crawlsarv-kb crawl https://docs.example.com --kb <id> --limit 100 --max-depth 3 --wait

searchsarv-kb search "python async" --kb <id> --limit 10 --wait

mapsarv-kb map https://example.com --kb <id> --limit 500 --wait

uploadsarv-kb upload ./report.pdf --kb <id> --ocr-language eng --wait

search vs find: search ingests new web results into the KB.find retrieves from what is already stored. Two different commands.

Tracking jobs

List jobs, follow one to completion, or act on it — logs, audit, cancel, delete.

sarv ▸ kb— zsh

$ sarv-kb jobs --kb kb_abc12345 --status completed

┌────────────┬────────┬─────────────┬───────┬─────────┐

│ ID │ Type │ Status │ Pages │ Created │

├────────────┼────────┼─────────────┼───────┼─────────┤

│ job_xyz999 │ scrape │ COMPLETED │ 3 │ 0s ago │

│ job_aaa111 │ crawl │ RUNNING │ 12 │ 1m ago │

└────────────┴────────┴─────────────┴───────┴─────────┘

$ sarv-kb job job_xyz999 --logs

10:00:05 info Starting scrape for https://example.com

10:00:30 info Job completed: 1 page stored

Other actions on a job: --wait, --audit,--source-md, --source-pdf out.pdf,--cancel, --delete.

Search & pages

Query stored content and browse the pages inside a KB.

sarv ▸ kb— zsh

$ sarv-kb find "billing webhook" --kb kb_abc12345

Results for "billing webhook" · 2 matches

◆ Configuring billing webhooks [0.94]

https://docs.example.com/billing/webhooks

Set up a webhook endpoint to receive billing events…

Browse with sarv-kb pages --kb <id> and fetch one in any format withsarv-kb page <pageId> --kb <id> --format markdown (json · markdown · html · links · images).

Files & export

Download the raw files behind a job, or export an entire KB for RAG pipelines.

sarv ▸ kb— zsh

$ sarv-kb export --kb kb_abc12345 --format jsonl -o kb.jsonl

⠹ Exporting → kb.jsonl (247)

✓ Exported 247 records → kb.jsonl

$ sarv-kb files export-kb --kb kb_abc12345 -o kb.zip

✓ Saved 18.4 MB to kb.zip

Stream export

export --format jsonl|csv → stdout or a file.

ZIP archives

files export-job / export-kb for full snapshots.

Global flags

These work on every command.

--jsonEmit raw JSON instead of the pretty view

--prettyPretty-print JSON (indent 2)

-o, --output <path>Write the result to a file

-k, --api-key <key>Override the stored API key for one command

--api-url <url>Override the backend URL for one command

Scripting

Pretty UI goes to stderr; stdout stays clean so you can pipe into jq and friends.

sarv ▸ kb— zsh

$ sarv-kb kb list --json | jq '.[].id'

"kb_abc12345"

"kb_def67890"

$ sarv-kb page p_123 --kb kb_abc12345 --format markdown > page.md

Local testing

Develop against a local backend without installing globally.

sarv ▸ kb— zsh

# point at any backend for a single command

$ sarv-kb --status --api-url https://crawl.sarv.com -k api-key

# or run the source directly

$ node bin/sarv-kb.js kb list

The CLI never talks HTTP directly (except the keyless /health ping) — all API access goes through a built-in client under src/api/ that mirrors thesarvcrawl surface. It is vendored (not a file: dependency), so the published package is fully self-contained and npm install -g works anywhere.

Explore the other integrations

Node SDK · Python SDK · MCP Server · n8n node

Back to Docs