> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Command cheatsheet

> Quick reference for Octoparse CLI commands: authentication, tasks, task groups, templates, scheduling, extraction, detect, and data export.

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

```bash theme={null}
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:

```bash theme={null}
octoparse capabilities --json
octoparse doctor --json
octoparse browser doctor --json
```

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

<Warning>
  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.
</Warning>

## Authentication

```bash theme={null}
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):

```bash theme={null}
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

```bash theme={null}
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.

<Note>
  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.
</Note>

With a local task file:

```bash theme={null}
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.

<Note>
  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.
</Note>

## Detect (create tasks from a URL)

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

```bash theme={null}
# 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](../guides/detect) for the full workflow.

## Local extraction

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
octoparse run <taskId> --jsonl
```

<Note>
  After detaching with `--detach`, use `octoparse local status`, `octoparse local pause`, `octoparse local resume`, or `octoparse local stop` to manage the run.
</Note>

## Cloud extraction

```bash theme={null}
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.

<Note>
  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.
</Note>

## Local run control

```bash theme={null}
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

```bash theme={null}
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     |

<Note>
  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.
</Note>

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

```bash theme={null}
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

```json theme={null}
{
  "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                    |

<Note>
  API key authentication is required for all functional commands, including local `--task-file` and `.otd` runs.
</Note>