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

# Task Commands

> Manage CVAT tasks from the command line

Tasks are the core annotation units in CVAT. The CLI provides comprehensive commands to create, manage, and work with tasks.

## Available Commands

* `task create` - Create a new task
* `task ls` - List all tasks
* `task delete` - Delete tasks
* `task frames` - Download specific frames
* `task export-dataset` - Export task as a dataset
* `task import-dataset` - Import annotations from a dataset
* `task backup` - Create a task backup
* `task create-from-backup` - Restore task from backup
* `task auto-annotate` - Auto-annotate using a local function

## task create

Create a new CVAT task with images or videos.

### Syntax

```bash theme={null}
cvat-cli task create <name> <resource_type> <resources...> [options]
```

### Arguments

| Argument        | Required | Description                                   |
| --------------- | -------- | --------------------------------------------- |
| `name`          | Yes      | Name of the task                              |
| `resource_type` | Yes      | Type of resources: `local`, `share`, `remote` |
| `resources`     | Yes      | List of file paths or URLs                    |

### Key Options

| Option                | Type    | Description                                               | Default         |
| --------------------- | ------- | --------------------------------------------------------- | --------------- |
| `--labels`            | JSON    | Labels specification                                      | `[]`            |
| `--project_id`        | Integer | Attach to existing project                                | None            |
| `--annotation_path`   | Path    | Path to annotation file                                   | None            |
| `--annotation_format` | String  | Annotation file format                                    | `CVAT 1.1`      |
| `--frame_step`        | Integer | Use every Nth frame                                       | 1               |
| `--start_frame`       | Integer | Start frame for video                                     | 0               |
| `--stop_frame`        | Integer | Stop frame for video                                      | End             |
| `--chunk_size`        | Integer | Frames per chunk                                          | Auto            |
| `--segment_size`      | Integer | Frames per segment                                        | Auto            |
| `--overlap`           | Integer | Overlapping frames between segments                       | 0               |
| `--image_quality`     | Integer | Image compression quality (0-100)                         | 70              |
| `--sorting-method`    | String  | Sort method: lexicographical, natural, predefined, random | lexicographical |
| `--use_cache`         | Boolean | Use cache                                                 | false           |
| `--use_zip_chunks`    | Boolean | Zip chunks before upload                                  | false           |
| `--copy_data`         | Boolean | Copy data from share                                      | false           |
| `--bug_tracker`       | URL     | Bug tracker URL                                           | None            |
| `--cloud_storage_id`  | Integer | Cloud storage ID                                          | None            |
| `--filename_pattern`  | String  | Pattern for filtering files                               | None            |

### Examples

#### Create Task with Local Images

```bash theme={null}
cvat-cli --auth user task create \
  "Car Detection Task" \
  local \
  image1.jpg image2.jpg image3.jpg \
  --labels '[{"name": "car"}, {"name": "person"}]'
```

#### Create Task Using Wildcards

```bash theme={null}
cvat-cli --auth user task create \
  "Batch Images" \
  local \
  images/*.jpg \
  --labels '[{"name": "object"}]'
```

#### Create Task in Existing Project

```bash theme={null}
cvat-cli --auth user task create \
  "Task 1" \
  local \
  data/*.png \
  --project_id 5
```

<Note>
  When creating a task within a project, you don't need to specify labels - they're inherited from the project.
</Note>

#### Create Task from Video

```bash theme={null}
cvat-cli --auth user task create \
  "Video Annotation" \
  local \
  video.mp4 \
  --labels '[{"name": "vehicle"}, {"name": "pedestrian"}]' \
  --frame_step 5 \
  --start_frame 100 \
  --stop_frame 500
```

#### Create Task from Remote URLs

```bash theme={null}
cvat-cli --auth user task create \
  "Remote Images" \
  remote \
  https://example.com/image1.jpg \
  https://example.com/image2.jpg \
  --labels '[{"name": "object"}]'
```

#### Create Task from Shared Storage

```bash theme={null}
cvat-cli --auth user task create \
  "Shared Dataset" \
  share \
  /mnt/shared/dataset/*.jpg \
  --labels '[{"name": "object"}]' \
  --copy_data
```

#### Create Task with Pre-annotations

```bash theme={null}
cvat-cli --auth user task create \
  "Pre-annotated Task" \
  local \
  images/*.jpg \
  --labels '[{"name": "car"}]' \
  --annotation_path ./annotations.xml \
  --annotation_format "CVAT 1.1"
```

## task ls

List all accessible tasks.

### Syntax

```bash theme={null}
cvat-cli task ls [options]
```

### Examples

```bash theme={null}
# List all tasks
cvat-cli --auth user task ls

# List tasks in JSON format
cvat-cli --auth user task ls --json

# List tasks in specific organization
cvat-cli --auth user --org team task ls
```

## task delete

Delete one or more tasks.

### Syntax

```bash theme={null}
cvat-cli task delete <task_id> [task_id ...]
```

### Examples

```bash theme={null}
# Delete single task
cvat-cli --auth user task delete 10

# Delete multiple tasks
cvat-cli --auth user task delete 10 11 12
```

<Warning>
  Deleting a task removes all associated data, annotations, and jobs. This cannot be undone.
</Warning>

## task frames

Download specific frames from a task.

### Syntax

```bash theme={null}
cvat-cli task frames <task_id> <frame_ids...> [options]
```

### Arguments

| Argument    | Required | Description               |
| ----------- | -------- | ------------------------- |
| `task_id`   | Yes      | Task ID                   |
| `frame_ids` | Yes      | Frame numbers to download |

### Options

| Option      | Description                         | Default           |
| ----------- | ----------------------------------- | ----------------- |
| `--outdir`  | Output directory                    | Current directory |
| `--quality` | Quality: `original` or `compressed` | `original`        |

### Examples

```bash theme={null}
# Download frames 0, 5, and 10
cvat-cli --auth user task frames 15 0 5 10

# Download frames to specific directory
cvat-cli --auth user task frames 15 0 1 2 3 4 \
  --outdir ./downloaded_frames

# Download compressed frames
cvat-cli --auth user task frames 15 0 10 20 \
  --quality compressed
```

Frames are saved as: `task_{task_id}_frame_{frame_id}.jpg`

## task export-dataset

Export a task as a dataset in various formats.

### Syntax

```bash theme={null}
cvat-cli task export-dataset <task_id> [filename] [options]
```

### Arguments

| Argument   | Required | Description              |                   |
| ---------- | -------- | ------------------------ | ----------------- |
| `task_id`  | Yes      | Task ID to export        |                   |
| `filename` | No       | Output file or directory | Current directory |

### Options

| Option                             | Description              | Default               |
| ---------------------------------- | ------------------------ | --------------------- |
| `--format`                         | Dataset format           | `CVAT for images 1.1` |
| `--with-images`                    | Include images in export | `false`               |
| `--completion_verification_period` | Status check interval    | `2`                   |

### Supported Formats

* CVAT for images 1.1
* CVAT for video 1.1
* YOLO 1.1
* COCO 1.0
* Pascal VOC 1.1
* MOTS PNG 1.0
* Segmentation mask 1.1
* LabelMe 3.0
* And many more...

### Examples

#### Export to Current Directory

```bash theme={null}
cvat-cli --auth user task export-dataset 10
```

#### Export in YOLO Format

```bash theme={null}
cvat-cli --auth user task export-dataset 10 \
  dataset.zip \
  --format "YOLO 1.1"
```

#### Export with Images

```bash theme={null}
cvat-cli --auth user task export-dataset 10 \
  full_dataset.zip \
  --format "COCO 1.0" \
  --with-images true
```

#### Export to Specific Directory

```bash theme={null}
cvat-cli --auth user task export-dataset 10 \
  ./exports/ \
  --format "Pascal VOC 1.1"
```

## task import-dataset

Import annotations into a task from a dataset file.

### Syntax

```bash theme={null}
cvat-cli task import-dataset <task_id> <filename> [options]
```

### Arguments

| Argument   | Required | Description               |
| ---------- | -------- | ------------------------- |
| `task_id`  | Yes      | Task ID                   |
| `filename` | Yes      | Annotation file to import |

### Options

| Option     | Description       | Default    |
| ---------- | ----------------- | ---------- |
| `--format` | Annotation format | `CVAT 1.1` |

### Examples

```bash theme={null}
# Import CVAT format annotations
cvat-cli --auth user task import-dataset 10 annotations.xml

# Import YOLO format annotations
cvat-cli --auth user task import-dataset 10 \
  yolo_annotations.zip \
  --format "YOLO 1.1"

# Import COCO format annotations
cvat-cli --auth user task import-dataset 10 \
  coco_annotations.json \
  --format "COCO 1.0"
```

## task backup

Create a complete backup of a task including data and annotations.

### Syntax

```bash theme={null}
cvat-cli task backup <task_id> [filename] [options]
```

### Arguments

| Argument   | Required | Description              |                   |
| ---------- | -------- | ------------------------ | ----------------- |
| `task_id`  | Yes      | Task ID to backup        |                   |
| `filename` | No       | Output file or directory | Current directory |

### Options

| Option                             | Description           | Default |
| ---------------------------------- | --------------------- | ------- |
| `--completion_verification_period` | Status check interval | `2`     |

### Examples

```bash theme={null}
# Backup to current directory
cvat-cli --auth user task backup 10

# Backup to specific file
cvat-cli --auth user task backup 10 task_10_backup.zip

# Backup to directory
cvat-cli --auth user task backup 10 ./backups/
```

The backup file contains:

* Task metadata and configuration
* All image/video data
* All annotations
* Task and job settings

## task create-from-backup

Restore a task from a backup file.

### Syntax

```bash theme={null}
cvat-cli task create-from-backup <filename> [options]
```

### Arguments

| Argument   | Required | Description            |
| ---------- | -------- | ---------------------- |
| `filename` | Yes      | Backup file to restore |

### Options

| Option                             | Description           | Default |
| ---------------------------------- | --------------------- | ------- |
| `--completion_verification_period` | Status check interval | `2`     |

### Examples

```bash theme={null}
# Restore from backup
cvat-cli --auth user task create-from-backup task_backup.zip

# Output: task ID
42
```

The command outputs the ID of the newly created task.

## task auto-annotate

Automatically annotate a task using a local machine learning function.

### Syntax

```bash theme={null}
cvat-cli task auto-annotate <task_id> [options]
```

### Arguments

| Argument  | Required | Description         |
| --------- | -------- | ------------------- |
| `task_id` | Yes      | Task ID to annotate |

### Options

| Option                     | Description                            | Default    |
| -------------------------- | -------------------------------------- | ---------- |
| `--function-module`        | Python module with annotation function | Required\* |
| `--function-file`          | Python file with annotation function   | Required\* |
| `--function-parameter`     | Function parameter (NAME=TYPE:VALUE)   | None       |
| `--clear-existing`         | Remove existing annotations            | false      |
| `--allow-unmatched-labels` | Allow new labels from function         | false      |
| `--conf-threshold`         | Confidence threshold for detections    | None       |
| `--conv-mask-to-poly`      | Convert masks to polygons              | false      |

\*Either `--function-module` or `--function-file` is required.

### Examples

#### Using a Module

```bash theme={null}
cvat-cli --auth user task auto-annotate 10 \
  --function-module my_detector \
  --clear-existing
```

#### Using a Python File

```bash theme={null}
cvat-cli --auth user task auto-annotate 10 \
  --function-file ./detector.py \
  --conf-threshold 0.5 \
  --clear-existing
```

#### With Function Parameters

```bash theme={null}
cvat-cli --auth user task auto-annotate 10 \
  --function-module my_detector \
  --function-parameter model=str:yolov8 \
  --function-parameter confidence=float:0.6 \
  --clear-existing
```

<Note>
  The function must follow the CVAT auto-annotation function specification. See the auto-annotation documentation for details on creating compatible functions.
</Note>

## Common Workflows

### Create and Export Task

```bash theme={null}
# Create task
TASK_ID=$(cvat-cli --auth user task create \
  "Export Test" \
  local \
  images/*.jpg \
  --labels '[{"name": "object"}]')

echo "Created task: $TASK_ID"

# After annotation, export
cvat-cli --auth user task export-dataset $TASK_ID \
  annotations.zip \
  --format "COCO 1.0"
```

### Backup and Restore

```bash theme={null}
# Backup task
cvat-cli --auth user task backup 10 backup.zip

# Restore to new task
NEW_TASK_ID=$(cvat-cli --auth user task create-from-backup backup.zip)
echo "Restored as task: $NEW_TASK_ID"
```

### Import, Annotate, Export

```bash theme={null}
# Import pre-annotations
cvat-cli --auth user task import-dataset 10 \
  pre_annotations.xml \
  --format "CVAT 1.1"

# Auto-annotate remaining frames
cvat-cli --auth user task auto-annotate 10 \
  --function-file detector.py

# Export final results
cvat-cli --auth user task export-dataset 10 \
  final_dataset.zip \
  --format "YOLO 1.1" \
  --with-images true
```

## Tips

1. **Resource Types**:
   * Use `local` for files on your machine
   * Use `share` for shared network storage
   * Use `remote` for URLs

2. **Large Datasets**: For large video or image sets, use `--chunk_size` and `--segment_size` to control memory usage

3. **Video Processing**: Use `--frame_step` to sample frames from videos (e.g., `--frame_step 10` uses every 10th frame)

4. **Quality Settings**: Adjust `--image_quality` (0-100) to balance file size and image quality

5. **Backup Regularly**: Create backups of important tasks before major changes

## Next Steps

* [See complete workflow examples](/cli/examples)
* [Learn about project commands](/cli/project-commands)
* [Configure authentication](/cli/configuration)