Task Commands

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

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

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

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

Create Task in Existing Project

cvat-cli --auth user task create \
  "Task 1" \
  local \
  data/*.png \
  --project_id 5

When creating a task within a project, you don’t need to specify labels - they’re inherited from the project.

Create Task from Video

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

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

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

Create Task with Pre-annotations

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

cvat-cli task ls [options]

Examples

# 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

cvat-cli task delete <task_id> [task_id ...]

Examples

# Delete single task
cvat-cli --auth user task delete 10

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

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

task frames

Download specific frames from a task.

Syntax

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

# 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

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

cvat-cli --auth user task export-dataset 10

Export in YOLO Format

cvat-cli --auth user task export-dataset 10 \
  dataset.zip \
  --format "YOLO 1.1"

Export with Images

cvat-cli --auth user task export-dataset 10 \
  full_dataset.zip \
  --format "COCO 1.0" \
  --with-images true

Export to Specific Directory

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

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

# 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

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

# 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

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

# 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

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

cvat-cli --auth user task auto-annotate 10 \
  --function-module my_detector \
  --clear-existing

Using a Python File

cvat-cli --auth user task auto-annotate 10 \
  --function-file ./detector.py \
  --conf-threshold 0.5 \
  --clear-existing

With Function Parameters

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

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

Common Workflows

Create and Export Task

# 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

# 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

# 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

Resource Types:
- Use local for files on your machine
- Use share for shared network storage
- Use remote for URLs
Large Datasets: For large video or image sets, use --chunk_size and --segment_size to control memory usage
Video Processing: Use --frame_step to sample frames from videos (e.g., --frame_step 10 uses every 10th frame)
Quality Settings: Adjust --image_quality (0-100) to balance file size and image quality
Backup Regularly: Create backups of important tasks before major changes

REST API

Python SDK

CLI Tool

​Available Commands

​task create

​Syntax

​Arguments

​Key Options

​Examples

​Create Task with Local Images

​Create Task Using Wildcards

​Create Task in Existing Project

​Create Task from Video

​Create Task from Remote URLs

​Create Task from Shared Storage

​Create Task with Pre-annotations

​task ls

​Syntax

​Examples

​task delete

​Syntax

​Examples

​task frames

​Syntax

​Arguments

​Options

​Examples

​task export-dataset

​Syntax

​Arguments

​Options

​Supported Formats

​Examples

​Export to Current Directory

​Export in YOLO Format

​Export with Images

​Export to Specific Directory

​task import-dataset

​Syntax

​Arguments

​Options

​Examples

​task backup

​Syntax

​Arguments

​Options

​Examples

​task create-from-backup

​Syntax

​Arguments

​Options

​Examples

​task auto-annotate

​Syntax

​Arguments

​Options

​Examples

​Using a Module

​Using a Python File

​With Function Parameters

​Common Workflows

​Create and Export Task

​Backup and Restore

​Import, Annotate, Export

​Tips

​Next Steps

Build docs developers (and LLMs) love

Available Commands

task create

Syntax

Arguments

Key Options

Examples

Create Task with Local Images

Create Task Using Wildcards

Create Task in Existing Project

Create Task from Video

Create Task from Remote URLs

Create Task from Shared Storage

Create Task with Pre-annotations

task ls

Syntax

Examples

task delete

Syntax

Examples

task frames

Syntax

Arguments

Options

Examples

task export-dataset

Syntax

Arguments

Options

Supported Formats

Examples

Export to Current Directory

Export in YOLO Format

Export with Images

Export to Specific Directory

task import-dataset

Syntax

Arguments

Options

Examples

task backup

Syntax

Arguments

Options

Examples

task create-from-backup

Syntax

Arguments

Options

Examples

task auto-annotate

Syntax

Arguments

Options

Examples

Using a Module

Using a Python File

With Function Parameters

Common Workflows

Create and Export Task

Backup and Restore

Import, Annotate, Export

Tips

Next Steps