CLI

• 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?

​

Why use the CLI?

• 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.

​

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, and screenshot, plus schema-driven subcommands for Google Search, Bing, Amazon, Walmart, Target, Reddit, 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 Reddit, TikTok, and YouTube.
• SERP monitoring – search Google and Bing with geo-targeting and parsed output.

​

Quick start

1. Create a free account at dashboard.decodo.com – up to 2K free requests, no credit card required.
2. Get your Web Scraping API Basic Auth token from the Decodo dashboard.
3. Install Node.js 18+ from nodejs.org (required for npm or npx).
4. Install the CLI using one of the methods below.
5. Authenticate and run your first scrape:

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

​

Installation

​

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

# Interactive - saves token to config
decodo setup

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

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

decodo whoami # Show token source (flag / env / config)
decodo reset  # Clear saved config

​

Test your setup

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

​

Commands

​

Tier-1 commands

​

Schema-driven target commands

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

​

Output modes

• 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. Process each line individually with tools such as jq.

# 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 JSON API endpoint
decodo scrape https://ip.decodo.com/json | jq '.proxy.ip'

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

​

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

​

Agent tooling

# 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

1. Require DECODO_AUTH_TOKEN or run decodo setup before scraping.
2. Prefer --format ndjson --full when parsing multiple results programmatically.
3. Use decodo targets to discover available target commands.
4. Use decodo <target> --help for schema-accurate flags.
5. Check exit codes to distinguish authentication, usage, and API errors.

​

MCP vs. CLI: when to use which

​

Environment variables

​

Exit codes

​

Troubleshooting

• No auth token found. Run decodo setup or export DECODO_AUTH_TOKEN.
• 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.

​

Related

• MCP Server – Use Decodo with MCP-compatible AI tools and IDEs.
• TypeScript SDK – Integrate the Web Scraping API into TypeScript and JavaScript projects.
• Agent Skills – Teach supported coding agents when and how to use Decodo.
• GitHub repository – View the CLI source code, examples, and latest releases.