Sandbox::https://help.decodo.com/docs/cli

Use the Decodo CLI to scrape websites, search engines, eCommerce platforms, and social media directly from your terminal.

View the CLI GitHub repository for the latest installation instructions, examples, and source code.

Decodo CLI (@decodo/cli) is an open-source command-line interface for the Decodo APIs. Scrape, search, map, and crawl from your terminal without writing HTTP client code, building custom parsers, or managing proxies.

Structured output in JSON, NDJSON, Markdown, and PNG screenshots
Server-side JavaScript rendering, anti-bot bypass, and CAPTCHA handling
115M+ residential IPs across 195+ locations
Pipe-friendly for jq, CI/CD, and coding agents

What is the Decodo CLI?

The Decodo CLI wraps every Web Scraping API target as a subcommand and adds shell-native output modes for scripting, automation, and AI agent workflows. It’s built with Node.js and TypeScript and is MIT-licensed. It provides a single command-line interface for accessing web data without maintaining scraping infrastructure yourself.

Why use the CLI?

Use the CLI when you need web scraping outside an IDE or MCP client:

Scripts and CI/CD – run scrapes in shell scripts, cron jobs, GitHub Actions, and pipelines.
Shell pipelines – pipe JSON or NDJSON output to jq, grep, databases, or custom tools.
Coding agents – invoke scraping as a subprocess from Cursor, Claude Code, Codex, Gemini CLI, or Windsurf.
Quick terminal access – scrape websites, search the web, or capture screenshots with a single command.

For MCP-based scraping inside an IDE, see the MCP Server instead. Use the CLI when you need direct shell access, scripting, or automation.

Key features

Web scraping from the terminal. Scrape websites, including JavaScript-heavy pages, without managing proxy rotation, JavaScript rendering, anti-bot handling, or CAPTCHA solving yourself.
Structured output for automation. Markdown (human-readable), JSON and NDJSON (pipe-friendly), and PNG screenshots built for scripts, data pipelines, and AI agent subprocesses.
Built-in support for popular targets. Tier-1 commands for scrape, search, map, crawl, and screenshot, plus schema-driven subcommands for Google Search and Bing, Amazon, Walmart, and Target, TikTok, YouTube, and more. Run decodo targets to list everything available.
Global proxy infrastructure. 115M+ residential IPs across 195+ locations with IP rotation and geo-targeting, backed by the Web Scraping API’s 99.99% success rate.
Pipe-friendly by design. Compact JSON when piped, human-readable output in a TTY, and explicit exit codes for authentication, validation, rate limit, and API errors.
Quick setup. Install with one command, or use npx without installing the CLI globally.

Use cases

Shell scripts and CI/CD – scrape or search in pipelines without embedding SDK logic.
Data pipelines – stream NDJSON results into jq, databases, or downstream tools.
Coding agent subprocesses – let AI agents call decodo search or decodo scrape directly.
eCommerce intelligence – query Amazon, Walmart, and Target from the terminal.
Social media data collection – gather posts and metadata from TikTok and YouTube.
SERP monitoring – search Google and Bing with geo-targeting and parsed output.

Quick start

Create a free account at dashboard.decodo.com – up to 10K free requests, no credit card required.
Get your Web Data API key from your Web Data API subscription on the Decodo dashboard. Older plans only have a basic authentication token, which also works.
Install Node.js 22+ from nodejs.org (required for npm or npx).
Install the CLI using one of the methods below.
Authenticate and run your first scrape:

decodo setup
decodo scrape https://ip.decodo.com
decodo search "decodo scraping api"

Installation

Requires Node.js 22 or later. The install script stops with Node.js v<version> found, but v22+ is required. on anything older.

macOS / Linux (recommended)

curl -fsSL https://decodo.github.io/cli/install.sh | sh

Windows (PowerShell)

irm https://decodo.github.io/cli/install.ps1 | iex

npm (any platform)

npm install -g @decodo/cli

Run without installing

npx @decodo/cli --version
npx @decodo/cli scrape https://ip.decodo.com --token "$DECODO_AUTH_TOKEN"

Authentication

Use the Web Data API key from your subscription on the Decodo dashboard. Older plans only have a basic authentication token, which works the same way - the CLI detects which one you provide, so every command below takes either.

# Interactive - saves the credential to config
decodo setup

# Non-interactive - useful in CI
decodo setup --token 'your-api-key'

# Environment variable - no saved config required
export DECODO_AUTH_TOKEN='your-api-key'

# Per-command override
decodo whoami --token 'your-api-key'

Precedence: --token flag → DECODO_AUTH_TOKEN env var → saved config (decodo setup).

decodo whoami # Show the active auth source and masked credential
decodo reset  # Clear saved config

search, map, and crawl call the Web Data API and need an API key. A basic authentication token is rejected with exit code 3:This command needs a Web Data API key; a basic auth token cannot call it.scrape, screenshot, and the target commands accept either credential.

Test your setup

Once installed and authenticated, try:

decodo scrape https://ip.decodo.com
decodo google-search "top articles hacker news" --page-count 5 --parse

You should see Markdown or parsed JSON output. If you see an authentication error, double-check your API key in the dashboard.

Commands

Tier-1 commands

Command	Description
`decodo scrape <url>`	Scrape a URL, Markdown by default (`--country`, `--headers`, `--target`)
`decodo search <query>`	Web search, parsed JSON results (`--geo`, `--locale`, `--page`)
`decodo map <url>`	List a site’s URLs, one per line (`--limit`, `--sitemap`, `--select-paths`)
`decodo crawl <url>`	Start a crawl and print its id; `--wait` prints pages as NDJSON
`decodo screenshot <url>`	Capture a PNG screenshot (`-o` file or directory)
`decodo targets`	List all scrape targets by group
`decodo setup`	Save your API key or auth token (`--token` for non-interactive)
`decodo whoami`	Show the active auth source and masked credential
`decodo reset`	Remove saved CLI configuration

Global flags: -V, --version, -v, --verbose, and --token <token>.

Search, map, and crawl

These three call the Web Data API and need an API key (see Authentication).

decodo search "rust web scraping" --geo DE | jq '.organic[].title'
decodo map https://example.com --limit 100 --select-paths "/blog/*"
decodo crawl https://example.com --limit 50 --wait --progress -o pages.ndjson

decodo crawl <url> returns right away with the crawl id. Manage a running crawl with:

decodo crawl status <id>
decodo crawl results <id> -o pages.ndjson
decodo crawl results <id> --wait -o pages.ndjson
decodo crawl cancel <id>

crawl results --wait lets an agent start a crawl, keep working, and collect the pages later. With --wait, the CLI polls every --poll-interval seconds (default 5) and gives up after --timeout seconds (default 3600, exit code 6) - the crawl keeps running until you cancel it. The crawl id goes to stderr as soon as the crawl starts. A truncated or cancelled crawl prints a warning; a faulted crawl still prints its pages, then exits 7.

Command	Key flags
`decodo search <query>`	`--geo`, `--locale`, `--page`, `--pretty`, `-o`
`decodo map <url>`	`--limit`, `--sitemap <include\|only\|skip>`, `--domain-filter <domain\|subdomain\|all>`, `--select-paths`, `--exclude-paths`, `--js-rendering`, `--geo`, `--locale`, `--full`, `--pretty`, `-o`
`decodo crawl <url>`	`--max-depth`, `--max-duration`, `--content-format <markdown\|html>`, all `map` site flags, plus `--wait`, `--progress`, `--poll-interval`, `--timeout`, `-o`
`decodo crawl status <id>`	`--pretty`
`decodo crawl results <id>`	`--no-content`, `--wait`, `--progress`, `--poll-interval`, `--timeout`, `-o`
`decodo crawl cancel <id>`	`--pretty`

Upgrading from 1.x: decodo search used to run the google_search scrape target and accepted --engine and --limit. It now calls the Web Data API and takes --geo, --locale, and --page only - passing --engine or --limit is a usage error (exit code 2). For the previous behaviour, use decodo google-search or decodo bing-search.

Schema-driven target commands

Every API target is also available as its own subcommand using the kebab-case name shown by decodo targets:

decodo google-search "decodo scraping api"
decodo universal https://ip.decodo.com
decodo universal --help

Use decodo <target> --help for target-specific flags (--parse, --geo, and others from the schema).

Output modes

By default, scrape commands print the first result’s content (parsed JSON when the target supports --parse, Markdown for decodo scrape).

Flag	Effect
`--full`	Print the full API response envelope
`--format ndjson`	One JSON object per result line on stdout (pipe-friendly)
`--pretty`	Indented JSON on stdout
`-o, --output <path>`	Write to a file instead of stdout
`-v, --verbose`	Print debug logs to stderr

TTY vs. pipe: When stdout is a terminal, the CLI uses human-readable output where possible. When output is piped or redirected, it writes raw bytes or compact JSON. Screenshots must be written to a file with -o or redirected because binary PNG output isn’t written directly to a TTY.
NDJSON output: With --format ndjson, stdout contains one JSON object per API result. Without --full, each line contains the result’s content; with --full, each line contains the complete result entry (content, status_code, url). There is no envelope-level .results[] on a single line - pipe each line through jq individually.

# Parsed JSON from Google Search
decodo google-search "query" --parse

# Full envelope, pretty-printed
decodo google-search "query" --full --pretty

# NDJSON stream for jq / agents
decodo google-search "query" --format ndjson --full | jq -c '.url'

Examples

Pipe-friendly workflows

# Search and extract titles
decodo google-search "rust web scraping" --page-count 3 --parse | jq '.results.results.organic[].title'

# Scrape a JSON API endpoint - --no-markdown keeps the response valid JSON
decodo universal https://ip.decodo.com/json --no-markdown | jq '.proxy.ip'

# Screenshot to file, then open
decodo screenshot https://example.com -o shot.png

decodo scrape returns Markdown, and the Markdown converter escapes underscores - so zip_code arrives as zip\_code. That is an invalid JSON escape, and piping it to jq fails with parse error: Invalid escape. When the target is a JSON endpoint, use decodo universal <url> --no-markdown instead.

Scraping geo-restricted content

# Request from a specific country
decodo scrape https://example.com --country US
decodo search "shoes" --geo DE
decodo google-search "shoes" --geo DE --parse

Use decodo <target> --help for all geo, locale, and target-specific options from the API schema.

Agent tooling

The Decodo CLI can also be used in AI agent and agentic workflows. Coding agents such as Cursor, Claude Code, Codex, Gemini CLI, and Windsurf can invoke the CLI as a shell subprocess instead of embedding scraping logic. Recommended patterns:

# Zero-install (good for CI and ephemeral agents)
npx --yes @decodo/cli search "topic" --token "$DECODO_AUTH_TOKEN"

# Global install (faster repeat calls)
decodo search "topic"
decodo scrape https://example.com --full --format ndjson

Guidelines for agents:

Require DECODO_AUTH_TOKEN or run decodo setup before scraping. Use an API key if the agent needs search, map, or crawl.
Prefer --format ndjson --full when parsing multiple results programmatically.
Use decodo targets to discover available target commands.
Use decodo <target> --help for schema-accurate flags.
Check exit codes to distinguish authentication, usage, and API errors.

MCP vs. CLI: when to use which

Use the CLI when your agent needs to scrape from a shell, terminal, CI/CD pipeline, or subprocess. For IDE-based agent scraping using the Model Context Protocol, see the MCP Server.

Environment variables

Variable	Description
`DECODO_AUTH_TOKEN`	API key or basic authentication token. Takes precedence over saved config but is overridden by `--token`.
`DECODO_CONFIG_HOME`	Override config directory. Defaults to `$XDG_CONFIG_HOME/decodo`, or `~/.config/decodo` if `$XDG_CONFIG_HOME` isn’t set.

Exit codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Usage error (invalid flags, missing args)
`3`	Authentication error - missing or invalid credential, or a basic authentication token used on `search`, `map`, or `crawl`
`4`	Validation error (invalid request parameters)
`5`	Rate limit
`6`	Timeout
`7`	API or network error

Troubleshooting

No API key or auth token found. Run decodo setup or export DECODO_AUTH_TOKEN.
This command needs a Web Data API key; a basic auth token cannot call it. You ran search, map, or crawl with a basic authentication token. Get an API key from the Web Data API playground and rerun decodo setup.
command not found: decodo. The install script configures your PATH automatically. If decodo still isn’t available, restart your terminal or rerun the install script. You can also use npx @decodo/cli.
Validation or API errors. Read the Error: message on stderr. Use --full to inspect the raw API response.
Screenshot TTY error. Use -o shot.png or redirect: decodo screenshot <url> > shot.png.

MCP Server – Use Decodo with MCP-compatible AI tools and IDEs.
TypeScript SDK – Integrate the Decodo APIs into TypeScript and JavaScript projects.
Python SDK – Integrate the Decodo APIs into Python projects.
Agent Skills – Teach supported coding agents when and how to use Decodo.
pobear – Open-source Go binary that scrapes directly and escalates to the Web Data API only when a request is blocked.
GitHub repository – View the CLI source code, examples, and latest releases.

Support

Need help or just want to say hello? Our support is available 24/7.
You can also reach us anytime via email at support@decodo.com.

Feedback

Can’t find what you’re looking for? Request an article!
Have feedback? Share your thoughts on how we can improve.

​What is the Decodo CLI?

​Why use the CLI?

​Key features

​Use cases

​Quick start

​Installation

​macOS / Linux (recommended)

​Windows (PowerShell)

​npm (any platform)

​Run without installing

​Authentication

​Test your setup

​Commands

​Tier-1 commands

​Search, map, and crawl

​Schema-driven target commands

​Output modes

​Examples

​Pipe-friendly workflows

​Scraping geo-restricted content

​Agent tooling

​MCP vs. CLI: when to use which

​Environment variables

​Exit codes

​Troubleshooting

​Related

Support

Feedback

What is the Decodo CLI?

Why use the CLI?

Key features

Use cases

Quick start

Installation

macOS / Linux (recommended)

Windows (PowerShell)

npm (any platform)

Run without installing

Authentication

Test your setup

Commands

Tier-1 commands

Search, map, and crawl

Schema-driven target commands

Output modes

Examples

Pipe-friendly workflows

Scraping geo-restricted content

Agent tooling

MCP vs. CLI: when to use which

Environment variables

Exit codes

Troubleshooting

Related