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

# Run your first task

> List Octoparse tasks, inspect a task, run it locally, check status, manage related workflows, and export collected data.

This page follows a typical extraction workflow: find a task, inspect it, run it, monitor it, and export the results.

<Note>
  v0.1.28 also adds task group workflows, template task workflows, cloud scheduling, and expanded data visibility. Exact commands for those new areas require confirmation from `octoparse capabilities --json` or v0.1.28 command help before using them in scripts.
</Note>

## List tasks

Query your task list:

```bash theme={null}
octoparse task list
```

Use pagination when needed:

```bash theme={null}
octoparse task list --page 2 --page-size 20
```

Limit the number of returned tasks:

```bash theme={null}
octoparse task list --limit 10
```

Search by keyword:

```bash theme={null}
octoparse task list --keyword news --page 1 --page-size 10
```

Use `--json` for machine-readable output:

```bash theme={null}
octoparse task list --json
```

## Work with task groups

Task groups help organize related tasks and find the tasks that belong to a group.

<Note>
  Requires confirmation: exact v0.1.28 commands for listing task groups and viewing tasks within a group were not available in the local CLI 0.1.24 help.
</Note>

## Inspect a task

Use the task ID from the task list:

```bash theme={null}
octoparse task inspect <taskId>
```

`task inspect` shows the task definition, field names, and related task metadata.

Validate a task before running it:

```bash theme={null}
octoparse task validate <taskId>
```

`task validate` checks whether the task is compatible with the current CLI runtime and can be executed locally. If validation fails, review the task definition, update the task in Octoparse, or contact Octoparse support.

## Run a task locally

Run:

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

Run in headless mode:

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

Stop local extraction after saving a maximum number of rows:

```bash theme={null}
octoparse run <taskId> --max-rows 100
```

Run in the background:

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

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

Write local run artifacts to a custom directory:

```bash theme={null}
octoparse run <taskId> --output ./runs
```

If you use `--output`, pass the same path to `data history` and `data export` later.

## Check or control a local run

Check local run status:

```bash theme={null}
octoparse local status <taskId>
```

<Note>
  Local run status is tracked by this CLI only and is not synchronized with the Octoparse desktop client status. This applies to local runs only.
</Note>

Pause and resume a local run:

```bash theme={null}
octoparse local pause <taskId>
octoparse local resume <taskId>
```

Stop a local run:

```bash theme={null}
octoparse local stop <taskId>
```

View local run history:

```bash theme={null}
octoparse local history <taskId>
```

Clean up local run state:

```bash theme={null}
octoparse local cleanup
```

`octoparse local cleanup` removes stale local run state and temporary files. It does not stop currently running tasks.

## Start or check a cloud run

Start cloud extraction:

```bash theme={null}
octoparse cloud start <taskId>
```

Check cloud status:

```bash theme={null}
octoparse cloud status <taskId>
```

View cloud history:

```bash theme={null}
octoparse cloud history <taskId>
```

Stop a cloud run:

```bash theme={null}
octoparse cloud stop <taskId>
```

## Configure cloud schedules

Cloud schedules are useful when a task should run on a recurring cadence, such as daily monitoring or weekly report collection.

<Note>
  Requires confirmation: exact v0.1.28 commands, schedule frequency values, timezone behavior, and limitations were not available in the local CLI 0.1.24 help.
</Note>

## Inspect and export data

Use data checks before export:

* **Count**: check whether data exists and how many rows are available.
* **Preview**: inspect sample rows before exporting.
* **Unexported**: identify data not yet exported.
* **Export**: retrieve full results.

<Note>
  Requires confirmation: exact v0.1.28 commands for count, preview, and unexported data were not available in the local CLI 0.1.24 help. Existing export commands are shown below.
</Note>

Export local data as XLSX:

```bash theme={null}
octoparse data export <taskId> --source local --format xlsx
```

Export cloud data as CSV:

```bash theme={null}
octoparse data export <taskId> --source cloud --format csv
```

Export to a specific file:

```bash theme={null}
octoparse data export <taskId> --source local --format csv --file ./result.csv
```

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

```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
```

## What's next

<CardGroup cols={2}>
  <Card title="Create tasks from a URL" href="../guides/detect">
    Use detect to generate a task file from any URL without the desktop app.
  </Card>

  <Card title="Browse all commands" href="../reference/command-cheatsheet">
    Review task, detect, local run, cloud run, authentication, and export commands.
  </Card>

  <Card title="Understand output and exit codes" href="../reference/output-and-exit-codes">
    Use JSON output, JSONL streams, and exit codes in scripts and automation.
  </Card>

  <Card title="Troubleshooting" href="../reference/troubleshooting">
    Fix common errors: auth failures, Chrome issues, Linux arm64, and export problems.
  </Card>
</CardGroup>