Project Commands

Create, list, and delete CVAT projects using the CLI

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 project
• project ls - List all projects
• project delete - Delete one or more projects

project create

Create a new CVAT project with optional labels and dataset import.

Syntax

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

Labels Format

Labels can be specified as:

• 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"

Output:

1

The command returns the ID of the created project.

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"}
]

Then create the project:

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.

Syntax

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

Output:

ID  Name                    Owner     Status
1   Vehicle Detection       admin     annotation
2   Self-Driving Car        admin     annotation
3   Pet Detection          user      annotation

List Projects in JSON Format

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.

Syntax

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"

Output:

42

You can use this ID to:

• 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

Tips

1. Save Project IDs: Capture project IDs in variables for later use:

   PROJECT_ID=$(cvat-cli --auth user project create "My Project" --labels '[{"name": "obj"}]')
   

2. Use Label Files: For projects with many labels or complex attributes, maintain labels in JSON files:

   cvat-cli project create "Project" --labels @labels.json
   

3. Organization Context: Always specify --org if working within an organization:

   cvat-cli --auth user --org team-name project create "Project"
   

4. Verify Creation: List projects after creation to confirm:

   cvat-cli --auth user project create "Test" && cvat-cli --auth user project ls
   

Next Steps

• Create tasks within projects
• See complete workflow examples
• Learn about authentication