Projects in CVAT are containers for organizing related tasks. The CLI provides commands to manage projects from the command line.
Available Commands
project create - Create a new projectproject ls - List all projectsproject delete - Delete one or more projects
project create
Create a new CVAT project with optional labels and dataset import.
cvat-cli project create <name> [options]
Arguments
| Argument | Required | Description |
|---|
name | Yes | Name of the project |
Options
| Option | Type | Description | Default |
|---|
--labels | JSON | Labels specification (string or file path) | [] |
--bug_tracker, --bug | URL | Bug tracker URL | None |
--dataset_path | Path | Path to dataset file to import | None |
--dataset_format | String | Format of dataset file | CVAT 1.1 |
--completion_verification_period | Float | Status check interval in seconds | 2 |
- JSON string:
'[{"name": "car"}, {"name": "person"}]'
- File path:
@labels.json (file containing JSON array)
Simple Labels Example
[
{"name": "car"},
{"name": "person"},
{"name": "bicycle"}
]
Labels with Attributes
[
{
"name": "car",
"attributes": [
{"name": "color", "input_type": "select", "values": ["red", "blue", "green"]},
{"name": "model", "input_type": "text"}
]
},
{
"name": "person",
"attributes": [
{"name": "age_group", "input_type": "select", "values": ["child", "adult", "senior"]}
]
}
]
Examples
Create a Simple Project
cvat-cli --auth user project create "Vehicle Detection"
Create Project with Labels
cvat-cli --auth user project create "Self-Driving Car" \
--labels '[{"name": "car"}, {"name": "pedestrian"}, {"name": "traffic_light"}]'
Create Project from Labels File
Create a labels.json file:
[
{"name": "cat"},
{"name": "dog"},
{"name": "bird"}
]
cvat-cli --auth user project create "Pet Detection" \
--labels @labels.json
Create Project with Bug Tracker
cvat-cli --auth user project create "Medical Imaging" \
--labels '[{"name": "tumor"}, {"name": "healthy"}]' \
--bug_tracker "https://github.com/myorg/myrepo/issues"
Create Project and Import Dataset
cvat-cli --auth user project create "Imported Project" \
--dataset_path ./annotations.zip \
--dataset_format "COCO 1.0"
project ls
List all accessible projects.
cvat-cli project ls [options]
Options
| Option | Description |
|---|
--json | Output in JSON format |
--filter | Filter projects (see Filtering) |
Examples
List All Projects
cvat-cli --auth user project ls
ID Name Owner Status
1 Vehicle Detection admin annotation
2 Self-Driving Car admin annotation
3 Pet Detection user annotation
cvat-cli --auth user project ls --json
List Projects in Organization
cvat-cli --auth user --org my-team project ls
project delete
Delete one or more projects by ID.
cvat-cli project delete <project_id> [project_id ...]
Arguments
| Argument | Required | Description |
|---|
project_id | Yes | One or more project IDs to delete |
Examples
Delete a Single Project
cvat-cli --auth user project delete 1
Delete Multiple Projects
cvat-cli --auth user project delete 1 2 3
Deleting a project will also delete all tasks within that project. This action cannot be undone.
Common Workflows
Create Project and Verify
Create a project and immediately list it:
# Create project and capture ID
PROJECT_ID=$(cvat-cli --auth user project create "My Project" \
--labels '[{"name": "object"}]')
echo "Created project ID: $PROJECT_ID"
# List projects to verify
cvat-cli --auth user project ls
Create Project with Complex Labels
For complex label configurations, use a JSON file:
labels.json:
[
{
"name": "vehicle",
"attributes": [
{
"name": "type",
"input_type": "select",
"values": ["car", "truck", "bus", "motorcycle"]
},
{
"name": "occluded",
"input_type": "checkbox"
}
],
"sublabels": [
{"name": "wheel"},
{"name": "window"}
]
},
{
"name": "pedestrian",
"attributes": [
{
"name": "posture",
"input_type": "select",
"values": ["standing", "walking", "sitting"]
}
]
}
]
cvat-cli --auth user project create "Advanced Detection" \
--labels @labels.json \
--bug_tracker "https://issues.example.com/projects/detection"
Batch Create Projects
Create multiple projects from a script:
#!/bin/bash
projects=("Dataset 1" "Dataset 2" "Dataset 3")
for project_name in "${projects[@]}"; do
echo "Creating project: $project_name"
cvat-cli --auth user project create "$project_name" \
--labels '[{"name": "object"}]'
done
cvat-cli --auth user project ls
Understanding Project IDs
When you create a project, the CLI outputs only the project ID:
cvat-cli --auth user project create "Test"
- Create tasks within the project:
cvat-cli task create "Task 1" local img.jpg --project_id 42
- Delete the project:
cvat-cli project delete 42
- Reference it in scripts and automation
-
Save Project IDs: Capture project IDs in variables for later use:
PROJECT_ID=$(cvat-cli --auth user project create "My Project" --labels '[{"name": "obj"}]')
-
Use Label Files: For projects with many labels or complex attributes, maintain labels in JSON files:
cvat-cli project create "Project" --labels @labels.json
-
Organization Context: Always specify
--org if working within an organization:
cvat-cli --auth user --org team-name project create "Project"
-
Verify Creation: List projects after creation to confirm:
cvat-cli --auth user project create "Test" && cvat-cli --auth user project ls
Next Steps
