> ## Documentation Index > Fetch the complete documentation index at: https://help.decodo.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI > Decodo CLI: an open-source command-line interface for the Decodo Web Scraping API. Scrape URLs, run SERP searches, and pull structured data from the terminal. Use the Decodo CLI to scrape websites, search engines, eCommerce platforms, and social media directly from your terminal. View the [CLI GitHub repository](https://github.com/Decodo/cli) for the latest installation instructions, examples, and source code. Decodo CLI (`@decodo/cli`) is an open-source command-line interface for the [Web Scraping API](https://decodo.com/scraping/web). Scrape and search 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**](/docs/mcp) 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, 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**](https://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**](https://dashboard.decodo.com/). 3. **Install Node.js 18+** from [**nodejs.org**](https://nodejs.org/) (required for npm or `npx`). 4. **Install the CLI** using one of the methods below. 5. **Authenticate and run** your first scrape: ```bash theme={null} decodo setup decodo scrape https://ip.decodo.com decodo search "decodo scraping api" ``` ## Installation Requires [**Node.js**](https://nodejs.org/) 18 or later. ### macOS / Linux (recommended) ```bash theme={null} curl -fsSL https://decodo.github.io/cli/install.sh | sh ``` ### Windows (PowerShell) ```powershell theme={null} irm https://decodo.github.io/cli/install.ps1 | iex ``` ### npm (any platform) ```bash theme={null} npm install -g @decodo/cli ``` ### Run without installing ```bash theme={null} npx @decodo/cli --version npx @decodo/cli scrape https://ip.decodo.com --token "$DECODO_AUTH_TOKEN" ``` ## Authentication Get your Basic Auth token from the [**Decodo dashboard**](https://dashboard.decodo.com/). ```bash theme={null} # 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' ``` **Precedence:** `--token` flag → `DECODO_AUTH_TOKEN` env var → saved config (`decodo setup`). ```bash theme={null} decodo whoami # Show token source (flag / env / config) decodo reset # Clear saved config ``` ## Test your setup Once installed and authenticated, try: ```bash theme={null} 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 Basic Auth token in the dashboard. ## Commands ### Tier-1 commands | Command | Description | | ------------------------- | -------------------------------------------------------- | | `decodo scrape ` | Scrape a URL (Markdown by default) | | `decodo search ` | Web search (`--engine google\|bing`, `--geo`, `--limit`) | | `decodo screenshot ` | Capture a PNG screenshot (`-o` file or directory) | | `decodo targets` | List all scrape targets by group | | `decodo setup` | Save the Basic Auth token interactively | | `decodo whoami` | Show the active authentication source | | `decodo reset` | Remove saved auth config | ### Schema-driven target commands Every API target is also available as its own subcommand using the kebab-case name shown by `decodo targets`: ```bash theme={null} decodo google-search "decodo scraping api" decodo universal https://ip.decodo.com decodo universal --help ``` Use `decodo --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 ` | 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. Process each line individually with tools such as `jq`. ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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 --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:** ```bash theme={null} # 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:** 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 --help` for schema-accurate flags. 5. 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**](/docs/mcp). ## Environment variables
Variable Description
`DECODO_AUTH_TOKEN` Basic Auth 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 token) | | `4` | Validation error (invalid request parameters) | | `5` | Rate limit | | `6` | Timeout | | `7` | API or network error | ## Troubleshooting * `No auth token found`. Run `decodo setup` or export `DECODO_AUTH_TOKEN`. * `command not found: decodo`. The [install script](https://decodo.github.io/cli/install.sh) 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 > shot.png`. *** ## Related * [**MCP Server**](/docs/mcp) – Use Decodo with MCP-compatible AI tools and IDEs. * [**TypeScript SDK**](/docs/typescript-sdk) – Integrate the Web Scraping API into TypeScript and JavaScript projects. * [**Agent Skills**](/docs/agent-skills) – Teach supported coding agents when and how to use Decodo. * [GitHub repository ](https://github.com/Decodo/cli)– View the CLI source code, examples, and latest releases. *** 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](mailto:support@decodo.com). Can't find what you're looking for? Request an article! \ Have feedback? Share your thoughts on how we can improve.