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