Octoparse CLI

Run and manage Octoparse extraction tasks from the command line.

With octoparse, you can browse cloud tasks, run tasks locally, manage active local runs, and export extracted data.

Requirements

• Node.js 20 or newer
• A valid Octoparse account or API key

Get started

1. Install

Install the CLI globally:

npm install -g @octoparse-ai/octoparse-cli

The installed command is:

octoparse

Check the installation:

octoparse --version
octoparse doctor

2. Log in

Most commands require Octoparse credentials. Run:

octoparse auth login

auth login lets you authenticate with OAuth or an API key. OAuth opens your browser and saves the token locally after you sign in.

To force OAuth login:

octoparse auth login --oauth

To authenticate with an API key, create one here:

https://www.octoparse.com/console/account-center/api-keys

If you have already copied the key, pass it directly:

octoparse auth login XXXXX

For CI or scripts, set an environment variable instead:

OCTO_ENGINE_API_KEY=xxx octoparse task list --json
OCTO_ENGINE_ACCESS_TOKEN=xxx octoparse task list --json

3. Use the CLI

List your tasks:

octoparse task list
octoparse task list --page 2 --page-size 20

Inspect a task:

octoparse task inspect <taskId>

Run a task locally:

octoparse run <taskId>

Local Chrome execution is supported on macOS x64/arm64, Windows x64, and Linux x64. Linux arm64 is not supported because Chrome for Testing does not currently provide a browser package for that platform. On Linux arm64, use a supported local platform or cloud extraction.

Use your signed-in Chrome or Edge profile

User-browser mode reuses an existing Chrome/Edge profile, including its cookies and login state. It is supported on Windows and macOS. Set it up in this order:

# Inspect Chrome or use --browser-id edge.
octoparse browser status --browser-id chrome --json
octoparse browser profiles --browser-id chrome --json

# Close the browser first, or let the CLI close it with --force-close.
octoparse browser install --browser-id chrome --profile "Default" --force-close --json

# Reopen Chrome once, confirm the Octoparse extension is enabled, then verify:
octoparse browser status --browser-id chrome --profile "Default" --json

# Persist this browser/profile for both run and detect:
octoparse browser use user --browser-id chrome --profile "Default" --json

browser status --json must report data.readyForUserBrowserRun=true before the profile is ready. Machine clients should follow data.nextActions or error.details.nextActions. Switch back at any time:

octoparse browser use independent --json

The saved mode applies to run and detect. Override one invocation with --browser independent|user, plus optional --browser-id chrome|edge and --profile <name>. User-browser mode cannot run headless. Agents should read browserRuntime.modes.user.setupRecipe from octoparse capabilities --json and perform every machine step themselves; reopening/enabling the extension remains an explicit user action.

Create a local task directly from a URL using CLI-based selection:

octoparse detect 'https://example.com/list' --auto --output task.json
octoparse detect 'https://example.com/search' --manual --query keyword --save-session --output task.json

detect uses the protected SmartProxy detector by default and requires configured credentials. Manual mode can save a cookies-only browser session for future local runs. Agent mode is available through --agent --agent-command. Because this option executes a local shell command, use only a trusted agent runner.

AI agent integration

When an LLM or agent helps a user create a task with Octoparse CLI, it should first run octoparse capabilities --json and then follow machineContract.recipes.createTaskFromUrlWithAgent. This recipe directs the agent to use detect --agent with a trusted agent runner for the shortest path to task creation. Add --run-sample <n> when sample rows are needed immediately. The lower-level prepare/plan/preview/apply workflow remains available for auditing and repairing tasks. This approach avoids asking users to interpret internal detection flags, defaulting to --auto, or writing JSON by hand.

Agent workflows generate a full-page screenshot, an annotated screenshot, and cropped screenshots of the top candidates when bounding boxes are available. Their paths are exposed through context.screenshot, context.visualArtifacts, and context.decisionSummary. Pass the user's natural-language request with --goal so the agent can evaluate candidates against both the page and the user's stated intent. The context also includes resultValidationPolicy. Agents should treat isolated missing fields in ads, topic cards, sponsored items, or mixed-format rows as normal partial data rather than repeatedly recreating the task.

Run in the background:

octoparse run <taskId> --detach

Query the local run status, or stop the local process running a task:

octoparse local status <taskId>
octoparse local stop <taskId>

Note: local run status is tracked by this CLI only and is not synchronized with the Octoparse desktop client status.

Export data:

octoparse data export <taskId> --source local --format xlsx
octoparse data export <taskId> --source cloud --format csv

Common commands

# Help and diagnostics
octoparse --help
octoparse doctor

# Authentication
octoparse auth login
octoparse auth login --oauth
octoparse auth login XXXXX
octoparse auth status
octoparse auth logout

# Task discovery
octoparse task list
octoparse task list --page 2 --page-size 20
octoparse task list --keyword news --page 2 --page-size 10
octoparse task inspect <taskId>

# Task creation
octoparse detect 'https://example.com/list' --auto --output task.json
octoparse detect 'https://example.com/search' --manual --query keyword --save-session --output task.json

# Local extraction
octoparse run <taskId>
octoparse run <taskId> --jsonl
octoparse run <taskId> --detach
octoparse local status <taskId>
octoparse local pause <taskId>
octoparse local resume <taskId>
octoparse local stop <taskId>

# Cloud extraction
octoparse cloud start <taskId>
octoparse cloud stop <taskId>
octoparse cloud status <taskId>
octoparse cloud history <taskId>

# Data
octoparse data history <taskId> --source local
octoparse data history <taskId> --source cloud
octoparse data export <taskId> --source local --format xlsx
octoparse data export <taskId> --source cloud --format csv

By default, local run artifacts are stored in ~/.octoparse/runs. If you customize the run artifact directory with --output, use the same --output again when reading local history or exporting local data:

octoparse run <taskId> --output ./runs
octoparse data history <taskId> --source local --output ./runs
octoparse data export <taskId> --source local --output ./runs --format xlsx

Authentication

Most commands require OAuth or API key credentials. Only setup and diagnostic commands such as --help, --version, doctor, capabilities, and auth can run before login.

For interactive OAuth login:

octoparse auth login
octoparse auth login --oauth

Create API keys in the Octoparse console:

https://www.octoparse.com/console/account-center/api-keys

If the API key is already copied:

octoparse auth login XXXXX

Use --no-open if you want to copy the URL manually:

octoparse auth login --no-open

For CI or scripts:

OCTO_ENGINE_API_KEY=xxx octoparse task list --json
OCTO_ENGINE_ACCESS_TOKEN=xxx octoparse task list --json

Credential precedence:

1. OCTO_ENGINE_API_KEY
2. OCTO_ENGINE_ACCESS_TOKEN
3. ~/.octoparse/credentials.json

Local task files

You can run or validate a local task definition file:

octoparse task validate <taskId> --task-file ./task.json
octoparse run <taskId> --task-file ./task.json
octoparse run sample --task-file ./sample.otd

Supported local task file types:

• .json
• .xml
• .otd

Kernel browser tasks are not supported in this CLI.

Machine-readable output

Use --json for one JSON response:

octoparse task list --json
octoparse local status <taskId> --json

Use --jsonl for local run event streams:

octoparse run <taskId> --jsonl

The stream includes captcha and proxy events when the runtime asks the CLI to resolve CAPTCHA or proxy resources automatically.

Local run artifacts are written under ~/.octoparse/runs by default, or under the selected --output directory when configured:

<output>/<runId>/
  meta.json
  events.jsonl
  logs.jsonl
  rows.jsonl

Troubleshooting

Check the local environment:

octoparse doctor

If the browser is not detected automatically, pass its path:

octoparse run <taskId> --chrome-path "/path/to/chrome"

Linux arm64 local execution is not supported, even with --chrome-path, because the bundled local runtime depends on Chrome for Testing platform support.

Clean stale local control state:

octoparse local cleanup
octoparse runs cleanup