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

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

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
• Learn about project commands
• Configure authentication