Command cheatsheet

Most functional commands require authentication unless noted. Use --json on supported commands for machine-readable output. Angle brackets such as <taskId> and <apiKey> indicate required placeholders. Replace them with your actual values.

Help and diagnostics

octoparse --help
octoparse --version
octoparse capabilities
octoparse doctor
octoparse doctor --chrome-path /path/to/chrome
octoparse browser doctor
octoparse browser doctor --chrome-path /path/to/chrome

Use --json for structured output:

octoparse capabilities --json
octoparse doctor --json
octoparse browser doctor --json

capabilities --json returns the full machine contract for AI agents and automation, including supported commands, output schemas, and the recommended task-creation workflow.

Some high-risk commands require stronger confirmation in v0.1.28. Depending on the command, users may need to pass an explicit confirmation flag or type a confirmation phrase. Confirm the exact syntax with octoparse capabilities --json or the v0.1.28 command help before documenting copy-paste examples.

Authentication

octoparse auth login              # choose OAuth or API key interactively
octoparse auth login --oauth      # browser-based OAuth login
octoparse auth login <apiKey>     # verify and store a copied API key
octoparse auth login --stdin      # read API key from stdin
octoparse auth login --no-open    # skip opening the browser
octoparse auth status
octoparse auth info
octoparse auth logout

Environment variable overrides (no stored credentials needed):

OCTO_ENGINE_API_KEY=xxx octoparse task list --json
OCTO_ENGINE_ACCESS_TOKEN=xxx octoparse task list --json
OCTO_ENGINE_API_BASE_URL=https://example.com OCTO_ENGINE_API_KEY=xxx octoparse task list

Tasks

octoparse task list
octoparse task list --page 2 --page-size 20
octoparse task list --limit 10
octoparse task list --keyword news
octoparse task inspect <taskId>
octoparse task validate <taskId>

Task groups

Use task groups to organize task workflows and find tasks within a group.

Requires confirmation: exact v0.1.28 commands for listing task groups and viewing tasks within a group were not present in the local CLI 0.1.24 help. Confirm with octoparse capabilities --json or v0.1.28 command help before adding examples.

With a local task file:

octoparse task inspect <taskId> --task-file <file.json|file.xml|file.otd>
octoparse task validate <taskId> --task-file <file.json|file.xml|file.otd>

Templates

v0.1.28 expands template workflows so users can view and search templates, create template tasks, and modify template tasks. Use “template task” or “task created from a template” for these workflows; do not imply the CLI creates arbitrary custom scraping workflows unless that is confirmed by the CLI contract.

Requires confirmation: exact template commands and flags for view, search, create template task, and modify template task were not present in the local CLI 0.1.24 help. Confirm with octoparse capabilities --json or v0.1.28 command help before adding examples.

Detect (create tasks from a URL)

Use detect to open the Octoparse extension browser, inspect a page, and generate a task file.

# Automatic — CLI picks the best candidate and generates a task file
octoparse detect <url> --auto
octoparse detect <url> --auto --goal "Extract product titles and prices" --output task.json

# Manual — opens a guided browser flow for selecting data regions
octoparse detect <url> --manual
octoparse detect <url> --manual --goal "Get search results"

# Search before detecting — submits a query on the entry page
octoparse detect <url> --auto --query "keyword" --goal "Extract search results"

For AI agent workflows, use the prepare / preview / apply sequence or the one-shot --agent wrapper. See Create tasks from a URL for the full workflow.

Local extraction

octoparse run <taskId>
octoparse run <taskId> --headless
octoparse run <taskId> --max-rows 100
octoparse run <taskId> --detach
octoparse run <taskId> --output ./runs
octoparse run <taskId> --chrome-path /path/to/chrome
octoparse run <taskId> --task-file task.json

Run timeout and debug options:

octoparse run <taskId> --timeout-ms 120000
octoparse run <taskId> --extension-timeout-ms 30000
octoparse run <taskId> --debug-bridge

Use --jsonl to stream run events line by line:

octoparse run <taskId> --jsonl

After detaching with --detach, use octoparse local status, octoparse local pause, octoparse local resume, or octoparse local stop to manage the run.

Cloud extraction

octoparse cloud start <taskId>
octoparse cloud stop <taskId>
octoparse cloud status <taskId>
octoparse cloud history <taskId>

Cloud scheduling

Use cloud schedules for recurring cloud task runs, such as daily price monitoring, weekly report collection, or periodic lead enrichment.

Requires confirmation: exact v0.1.28 schedule command syntax, timezone handling, frequency values, and schedule limitations were not present in the local CLI 0.1.24 help. Confirm with octoparse capabilities --json or v0.1.28 command help before adding examples.

Local run control

octoparse local status <taskId>
octoparse local pause <taskId>
octoparse local resume <taskId>
octoparse local stop <taskId>
octoparse local history <taskId>
octoparse local export <taskId> --format xlsx
octoparse local export <taskId> --format csv --file ./result.csv
octoparse local export <taskId> --lot-id <lotId> --format json
octoparse local cleanup

octoparse local cleanup removes stale local run state and temporary files. It does not stop active runs.

Data history, preview, and export

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
octoparse data export <taskId> --source local --format csv --file ./result.csv
octoparse data export <taskId> --source local --lot-id <lotId> --format json

Supported export formats: xlsx, csv, html, json, xml Use data commands for different checkpoints:

Need	Use
Check whether data exists and how many rows are available	Record count
Inspect sample rows before exporting	Preview data
Identify rows not yet exported	Unexported data
Retrieve full results	Export data

Requires confirmation: exact v0.1.28 commands and flags for record count, preview data, and unexported data were not present in the local CLI 0.1.24 help. Confirm with octoparse capabilities --json or v0.1.28 command help before adding examples.

If you used a custom output directory during local extraction, pass the same --output path when reading history or exporting:

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

Task file format

{
  "taskId": "abc123",
  "taskName": "Example",
  "xml": "... original OTD XML ...",
  "xoml": "... transformed BPMN XOML ...",
  "fieldNames": ["title", "url"],
  "workflowSetting": {},
  "brokerSettings": {},
  "userAgent": "Mozilla/5.0 ...",
  "disableAD": false
}

Field	Meaning
`taskId`	Octoparse task ID
`taskName`	Human-readable task name
`xml`	Original OTD XML definition
`xoml`	Transformed workflow definition used by the engine
`fieldNames`	Output field names expected from the task
`workflowSetting`	Task workflow settings
`brokerSettings`	Runtime or broker-related task settings
`userAgent`	Browser user agent used during extraction
`disableAD`	Whether ad blocking is disabled

API key authentication is required for all functional commands, including local --task-file and .otd runs.

OVERVIEW

GET STARTED

GUIDES

REFERENCE

Help and diagnostics

Authentication

Tasks

Task groups

Templates

Detect (create tasks from a URL)

Local extraction

Cloud extraction

Cloud scheduling

Local run control

Data history, preview, and export

Task file format

​Help and diagnostics

​Authentication

​Tasks

​Task groups

​Templates

​Detect (create tasks from a URL)

​Local extraction

​Cloud extraction

​Cloud scheduling

​Local run control

​Data history, preview, and export

​Task file format

Help and diagnostics

Authentication

Tasks

Task groups

Templates

Detect (create tasks from a URL)

Local extraction

Cloud extraction

Cloud scheduling

Local run control

Data history, preview, and export

Task file format