ScrapeAtlas CLI

The official terminal client for the ScrapeAtlas API. Requires Node.js 22 or newer and a ScrapeAtlas customer API key.

npm install -g @scrapeatlas/cli
scrapeatlas auth login
scrapeatlas bluesky profile --handle bsky.app --pretty

Or run without a global installation:

npx @scrapeatlas/cli list

Discover and call endpoints

scrapeatlas list
scrapeatlas list reddit
scrapeatlas bluesky profile --help
scrapeatlas list bluesky --json
scrapeatlas bluesky posts --handle bsky.app --limit 10
scrapeatlas call blueskyProfile --input '{"handle":"bsky.app"}'
scrapeatlas reddit search --input @request.json

Commands and request schemas are generated from the API's gateway/MCP catalog. list <platform> --json includes operation IDs, paths, descriptions and JSON Schemas. Update your installed catalog with npm install -g @scrapeatlas/cli@latest, or run npx @scrapeatlas/cli@latest list. Check your version with scrapeatlas --version. API validation remains authoritative for cross-field rules and URL refinements.

Use scrapeatlas <platform> <action>. Parameter flags accept the API's original camelCase/snake_case name and its kebab-case spelling (--user-id). Boolean parameters use --flag / --no-flag; explicit booleans, arrays and nested objects can be passed through --input '<JSON object>' or --input @file.json. Required parameters, types and structural bounds are checked locally before a request. Duplicate parameters and unknown options are rejected.

Authentication

Get a customer API key from your dashboard. auth login reads a hidden key and verifies it through the gateway before saving. For noninteractive login, pipe a key to scrapeatlas auth login --stdin.

scrapeatlas auth status
scrapeatlas auth logout

Credential priority is --api-key, then SCRAPEATLAS_API_KEY, then stored login. Prefer the environment variable in CI; a flag can appear in shell history and process lists. auth status reports the credential source without printing the key; it does not make a live verification request. Logout removes the stored key; it does not revoke the key in your account or clear an environment variable.

Config is stored in $XDG_CONFIG_HOME/scrapeatlas/config.json, defaulting to ~/.config/scrapeatlas/config.json. Override with SCRAPEATLAS_CONFIG_DIR. The config directory is mode 0700 and the file is mode 0600 on POSIX. The file contains a plaintext key protected by those permissions; it is not a keychain.

The default API origin is https://api.scrapeatlas.com. --base-url overrides SCRAPEATLAS_BASE_URL, the saved origin, then the default. HTTPS origins are supported; HTTP is allowed only on loopback for local development. Stored keys are used only for their saved origin. An explicit flag/environment key can be used with a custom gateway. No cookies or provider worker secrets are required.

Output and failures

scrapeatlas bluesky profile --handle bsky.app | jq '.followersCount'
scrapeatlas bluesky profile --handle bsky.app --pretty
scrapeatlas bluesky profile --handle bsky.app --output profile.json
scrapeatlas bluesky profile --handle bsky.app --envelope

Default stdout is the complete compact gateway JSON. --pretty indents it. --envelope wraps it as {httpStatus, body, requestId?, retryAfter?}. --output writes a new file and prints only its absolute path; existing files are never overwritten. Diagnostics are structured JSON on stderr and never include request parameters, credentials, or retrieved content.

Nulls, failed lookups, partial coverage, ordering and pagination tokens are preserved. A usable partial response exits 0; inspect status and coverage before treating results as complete. HTTP errors or explicit success: false, status: failed and status: challenged exit 1 while keeping the full API body on stdout. Local argument/config/file errors exit 2. Ctrl-C during login exits 130.

Each call makes one gateway request, with no retries, automatic pagination, redirect following or media downloads. Pass the returned cursor explicitly for another page. Requests are capped at 64 KiB and responses at 16 MiB. The deadline covers headers and body: 90 seconds by default, configurable using --timeout <milliseconds> from 1 to 120000. Failures never masquerade as empty successes. This version exports JSON only and does not install agent configs, run an MCP server, perform browser signup, or supply a TypeScript SDK.

License and support

MIT — see LICENSE. For help or bug reports, contact ScrapeAtlas or email [email protected].