ContextQMD
Back to Cvat

Command line interface (CLI)

site/content/en/docs/api_sdk/cli/_index.md

2.73.020.1 KB
Original Source

Overview

A simple command line interface for working with CVAT. At the moment it implements a basic feature set but may serve as the starting point for a more comprehensive CVAT administration tool in the future.

The following subcommands are supported:

  • Projects:

    • backup - back up a project
    • create - create a new project
    • create-from-backup - create a project from a backup file
    • delete - delete projects
    • export-dataset - export a project as a dataset
    • import-dataset - create project tasks from a dataset
    • ls - list all projects

  • Tasks:

    • create - create a new task
    • create-from-backup - create a task from a backup file
    • delete - delete tasks
    • ls - list all tasks
    • frames - download frames from a task
    • export-dataset - export a task as a dataset
    • import-dataset - import annotations into a task from a dataset
    • backup - back up a task
    • auto-annotate - automatically annotate a task using a local function

  • Functions (Enterprise/Cloud only):

    • create-native - create a function that can be powered by an agent
    • delete - delete a function
    • run-agent - process requests for a native function

Installation

To install an official release of CVAT CLI, use this command:

bash
pip install cvat-cli

We support Python versions 3.10 and higher.

Usage

The general form of a CLI command is:

console
$ cvat-cli <common options> <resource> <action> <options>

where:

  • <common options> are options shared between all subcommands;
  • <resource> is a CVAT resource, such as task;
  • <action> is the action to do with the resource, such as create;
  • <options> is any options specific to a particular resource and action.

You can list available subcommands and options using the --help option:

$ cvat-cli --help # get help on available common options and resources
$ cvat-cli <resource> --help # get help on actions for the given resource
$ cvat-cli <resource> <action> --help # get help on action-specific options

The CLI implements alias subcommands for some task actions, so that, for example, cvat-cli ls works the same way as cvat-cli task ls. These aliases are provided for backwards compatibility and are deprecated. Use the task <action> form instead.

Authentication

CLI supports 2 authentication options:

  • Personal Access Token (PAT) authentication, with an access token value
  • Password authentication, with a username and a password

Personal Access Token (PAT) authentication requires a token that can be configured in the user settings section in the UI. It is the recommended authentication option for most clients. {{< ilink "/docs/api_sdk/access_tokens" "Read more." >}}

Password authentication requires a username and password pair. For better security it's recommended to use a Personal Access Token (PAT) instead, if possible.

{{< tabpane text=true >}}

{{%tab header="Personal Access Token (PAT) authentication" %}}

A Personal Access Token can only be used via the CVAT_ACCESS_TOKEN environment variable. This variable is prioritized over other environment variables used for authentication.

bash
export CVAT_ACCESS_TOKEN="token value"
cvat-cli task ls

{{% /tab %}}

{{%tab header="Password authentication" %}}

Credentials can be specified via the --auth global CLI parameter. The password can be passed after the colon (:) separator or via the PASS environment variable. For better security, it's recommended to use the PASS environment variable or Personal Access Tokens.

bash
cvat-cli --auth "username:password" task ls
bash
export PASS="password"
cvat-cli --auth "username" task ls

The --auth parameter can also be omitted. In this case, the CLI will try to use the current OS user as the username. If the PASS environment variable is configured, it's value will be used for the password. Otherwise, the password will be requested for input.

bash
cvat-cli task ls

{{% /tab %}}

{{< /tabpane >}}

Persistent authentication (profiles)

The CLI can remember a server URL and a Personal Access Token (PAT) locally, so that everyday commands do not have to repeat --server-host / --auth or leak credentials into shell history. Each remembered profile is self-contained: it bundles one server with one PAT.

Profiles are stored as a JSON file with 0600 (owner read/write only) mode inside a 0700 directory. The CLI refuses to read or write the file if either it or its parent directory is group- or world-accessible. On Windows the check is best-effort. The location follows the platform convention:

PlatformPath
Linux${XDG_CONFIG_HOME:-$HOME/.config}/cvat-sdk/auth.json
macOS~/Library/Application Support/cvat-sdk/auth.json
Windows%LOCALAPPDATA%\CVAT.ai\cvat-sdk\auth.json

Local profiles are only available for PAT authentication method. Username and password cannot be remembered this way.

Managing profiles

Use cvat-cli profile and cvat-cli config to create and manage profiles. These commands operate on the local file and do not talk to the server (except that profile create optionally reads the token's name from the server when you did not supply one).

bash
# Save a profile. Prompted for the token (no echo) if omitted.
cvat-cli --server-host https://app.cvat.ai profile create --name mycvat --set-default

# Save a profile by pasting the token, and pick a nickname:
cvat-cli --server-host https://app.cvat.ai profile create --name mycvat "<paste-token-here>"

# Import a plain-text token:
cvat-cli --server-host https://app.cvat.ai profile create --name mycvat --file ~/Downloads/cvat-token.txt

# A JSONC envelope containing the token, server, and profile name needs no extra arguments:
cvat-cli profile create --file ~/Downloads/cvat-token-my-laptop.json

# Inspect and manage the store:
cvat-cli profile list                # lists names, servers, and the default marker
cvat-cli profile list --names-only   # names only, one per line (script-friendly)
cvat-cli profile default             # print the current default profile
cvat-cli profile default staging     # make "staging" the default
cvat-cli profile default --unset     # unset the default
cvat-cli profile delete staging      # remove the profile (does not revoke the token)

# Set a fallback server used when neither --server-host nor --profile is given:
cvat-cli config default-server https://app.cvat.ai
cvat-cli config default-server        # print the current default server
cvat-cli config default-server --unset

Token envelope files accept JSONC syntax, including comments and trailing commas. If the server has moved since the envelope was downloaded, pass --server-host to override the embedded server URL:

bash
cvat-cli --server-host https://new.example.com profile create \
  --file ~/Downloads/cvat-token-my-laptop.json

The server-side token is not revoked when a profile is deleted; use the CVAT UI or API to revoke it.

Selecting a profile per command

The global --profile <name> flag selects a saved profile for a single command. It is mutually exclusive with --server-host, --server-port, and --auth:

bash
cvat-cli --profile mycvat task ls
cvat-cli --profile staging task create "task 1" --labels labels.json local file.jpg

Resolution order

The CLI first tries to select a profile:

  1. An explicit --profile NAME, if provided. It supplies both the server and PAT, and cannot be combined with --server-host, --server-port, or --auth.
  2. Otherwise, the default profile, if one is configured and no explicit server or credential was provided. CVAT_ACCESS_TOKEN counts as an explicit credential.

If a profile is selected, it supplies both values and resolution stops. Otherwise, the credential and server are resolved independently.

Credential resolution order:

  1. --auth USER[:PASS], if provided. When PASS is omitted, the CLI uses the PASS environment variable or prompts for the password.
  2. CVAT_ACCESS_TOKEN, if set.
  3. The current OS username, with the PASS environment variable or a password prompt.

Server resolution order:

  1. --server-host, if provided. --server-port is applied to the selected host; if only --server-port is provided, the host comes from the next available source below.
  2. The server configured by cvat-cli config default-server, if set.
  3. The built-in default, http://localhost.

Supplying an explicit credential or server prevents the CLI from borrowing the other value from the default profile.

Examples - tasks

Create

Description of the options you can find in {{< ilink "/docs/workspace/tasks-page#create-annotation-task" "Creating an annotation task" >}} section.

For create a task you need file contain labels in the json format, you can create a JSON label specification by using the {{< ilink "/docs/workspace/tasks-page#create-annotation-task#labels" "label constructor" >}}.

<details> <summary>Example JSON labels file</summary>
json
[
    {
        "name": "cat",
        "attributes": []
    },
    {
        "name": "dog",
        "attributes": []
    }
]
</details>
  • Create a task named "new task" on the default server http://localhost, labels from the file "labels.json" and local images "file1.jpg" and "file2.jpg", the task will be created as current user:
    bash
    cvat-cli task create "new task" --labels labels.json local file1.jpg file2.jpg
  • Create a task named "task 1" on the server https://example.com labels from the file "labels.json" and local image "image1.jpg", the task will be created as user "user-1":
    bash
    cvat-cli --server-host https://example.com --auth user-1 task create "task 1" \
--labels labels.json local image1.jpg
  • Create a task named "task 1" on the default server, with labels from "labels.json" and local image "file1.jpg", as the current user, in organization "myorg":
    bash
    cvat-cli --org myorg task create "task 1" --labels labels.json local file1.jpg
  • Create a task named "task 1", labels from the project with id 1 and with a remote video file, the task will be created as user "user-1":
    bash
    cvat-cli --auth user-1:password task create "task 1" --project_id 1 \
remote https://github.com/opencv/opencv/blob/master/samples/data/vtest.avi?raw=true
  • Create a task named "task 1 sort random", with labels "cat" and "dog", with chunk size 8, with sorting-method random, frame step 10, copy the data on the CVAT server, with use zip chunks and the video file will be taken from the shared resource:
    bash
    cvat-cli task create "task 1 sort random" --labels '[{"name": "cat"},{"name": "dog"}]' --chunk_size 8 \
--sorting-method random --frame_step 10 --copy_data --use_zip_chunks share //share/dataset_1/video.avi
  • Create a task named "task from dataset_1", labels from the file "labels.json", with link to bug tracker, image quality will be reduced to 75, annotation in the format "CVAT 1.1" will be taken from the file "annotation.xml", the data will be loaded from "dataset_1/images/", the task will be created as user "user-2", and the password will need to be entered additionally:
    bash
    cvat-cli --auth user-2 task create "task from dataset_1" --labels labels.json \
--bug_tracker https://bug-tracker.com/0001 --image_quality 75 --annotation_path annotation.xml \
--annotation_format "CVAT 1.1" local dataset_1/images/
  • Create a task named "segmented task 1", labels from the file "labels.json", with overlay size 5, segment size 100, with frames 5 through 705, using cache and with a remote video file:
    bash
    cvat-cli task create "segmented task 1" --labels labels.json --overlap 5 --segment_size 100 \
--start_frame 5 --stop_frame 705 --use_cache \
remote https://github.com/opencv/opencv/blob/master/samples/data/vtest.avi?raw=true
  • Create a task named "task with filtered cloud storage data", with filename_pattern test_images/*.jpeg and using the data from the cloud storage resource described in the manifest.jsonl:
    bash
    cvat-cli task create "task with filtered cloud storage data" --labels '[{"name": "car"}]'\
--use_cache --cloud_storage_id 1 --filename_pattern "test_images/*.jpeg" share manifest.jsonl
  • Create a task named "task with filtered cloud storage data" using all data from the cloud storage resource described in the manifest.jsonl by specifying filename_pattern *:
    bash
    cvat-cli task create "task with filtered cloud storage data" --labels '[{"name": "car"}]'\
--use_cache --cloud_storage_id 1 --filename_pattern "*" share manifest.jsonl

Delete

  • Delete tasks with IDs "100", "101", "102" , the command will be executed from "user-1" having delete permissions:
    bash
    cvat-cli --auth user-1:password task delete 100 101 102

List

  • List all tasks:
    bash
    cvat-cli task ls
  • List all tasks in organization "myorg":
    bash
    cvat-cli --org myorg task ls
  • Save list of all tasks into file "list_of_tasks.json":
    bash
    cvat-cli task ls --json > list_of_tasks.json

Frames

  • Save frame 12, 15, 22 from task with id 119, into "images" folder with compressed quality:
    bash
    cvat-cli task frames --outdir images --quality compressed 119 12 15 22

Export as a dataset

  • Export annotation task with id 103, in the format CVAT for images 1.1 and save to the file "output.zip":
    bash
    cvat-cli task export-dataset --format "CVAT for images 1.1" 103 output.zip
  • Export annotation task with id 104, in the format COCO 1.0 and save to the file "output.zip":
    bash
    cvat-cli task export-dataset --format "COCO 1.0" 104 output.zip

Import annotations from a dataset

  • Import annotation into task with id 105, in the format CVAT 1.1 from the file "annotation.xml":
    bash
    cvat-cli task import-dataset --format "CVAT 1.1" 105 annotation.xml

Back up a task

  • Back up task with id 136 to file "task_136.zip":
    bash
    cvat-cli task backup 136 task_136.zip

Create from backup

  • Create a task from backup file "task_backup.zip":
    bash
    cvat-cli task create-from-backup task_backup.zip

Auto-annotate

This command provides a command-line interface to the {{< ilink "/docs/api_sdk/sdk/auto-annotation" "auto-annotation API" >}}.

It can auto-annotate using AA functions implemented in one of the following ways:

  1. As a Python module directly implementing the AA function protocol. Such a module must define the required attributes at the module level.

    For example:

    python
    import cvat_sdk.auto_annotation as cvataa

spec = cvataa.DetectionFunctionSpec(...)

def detect(context, image):
    ...

  2. As a Python module implementing a factory function named create. This function must return an object implementing the AA function protocol. Any parameters specified on the command line using the -p option will be passed to create.

    For example:

    python
    import cvat_sdk.auto_annotation as cvataa

class _MyFunction:
    def __init__(...):
        ...

    spec = cvataa.DetectionFunctionSpec(...)

    def detect(context, image):
        ...

def create(...) -> cvataa.DetectionFunction:
    return _MyFunction(...)

  • Annotate the task with id 137 with the predefined torchvision detection function, which is parameterized:

    bash
    cvat-cli task auto-annotate 137 --function-module cvat_sdk.auto_annotation.functions.torchvision_detection \
    -p model_name=str:fasterrcnn_resnet50_fpn_v2 -p box_score_thresh=float:0.5

  • Annotate the task with id 138 with an AA function defined in my_func.py:

    bash
    cvat-cli task auto-annotate 138 --function-file path/to/my_func.py

Note that this command does not modify the Python module search path. If your function module needs to import other local modules, you must add your module directory to the search path if it isn't there already.

  • Annotate the task with id 139 with a function defined in the my_func module located in the my-project directory, letting it import other modules from that directory.
    bash
    PYTHONPATH=path/to/my-project cvat-cli task auto-annotate 139 --function-module my_func

Examples - projects

Create

While creating a project, you may optionally define its labels. The project create command accepts labels in the same format as the task create command; see that command's examples for more information.

  • Create a project named "new project" on the default server http://localhost, with labels from the file "labels.json":
    bash
    cvat-cli project create "new project" --labels labels.json
  • Create a project from a dataset in the COCO format:
    bash
    cvat-cli project create "new project" --dataset_path coco.zip --dataset_format "COCO 1.0"
  • Create a project from a dataset and check the import status every second:
    bash
    cvat-cli project create "new project" --dataset_path coco.zip --dataset_format "COCO 1.0" \
    --completion_verification_period 1

Delete

  • Delete projects with IDs "100", "101", "102":
    bash
    cvat-cli project delete 100 101 102

List

  • List all projects:
    bash
    cvat-cli project ls
  • Save list of all projects into file "list_of_projects.json":
    bash
    cvat-cli project ls --json > list_of_projects.json

Back up a project

  • Back up project with id 25 to file project_25.zip:
    bash
    cvat-cli project backup 25 project_25.zip

Create from backup

  • Create a project from backup file project_backup.zip:
    bash
    cvat-cli project create-from-backup project_backup.zip

Export as a dataset

  • Export project with id 103 in the format CVAT for images 1.1 and save to the file "project.zip":
    bash
    cvat-cli project export-dataset --format "CVAT for images 1.1" 103 project.zip
  • Export project with id 104 in the format COCO 1.0, including images, and save to the file "project.zip":
    bash
    cvat-cli project export-dataset --format "COCO 1.0" --with-images yes 104 project.zip
  • Export project with id 105 to the current directory, using the server-generated filename:
    bash
    cvat-cli project export-dataset --format "CVAT for images 1.1" 105

Create tasks from a dataset

  • Create tasks in project with id 106 from the file "coco.zip" in the format COCO 1.0:

    bash
    cvat-cli project import-dataset --format "COCO 1.0" 106 coco.zip

    The project must have labels compatible with the dataset being imported. The uploaded dataset must include image data, because the command creates new tasks with images and annotations.

Examples - functions

Note: The functionality described in this section can only be used with the CVAT Enterprise or CVAT Cloud.

Create

  • Create a function that uses a detection model from torchvision and run an agent for it:

    cvat-cli function create-native "Faster R-CNN" \
    --function-module cvat_sdk.auto_annotation.functions.torchvision_detection \
    -p model_name=str:fasterrcnn_resnet50_fpn_v2
cvat-cli function run-agent <ID printed by previous command> \
    --function-module cvat_sdk.auto_annotation.functions.torchvision_detection \
    -p model_name=str:fasterrcnn_resnet50_fpn_v2

  • Create and run an SAM2 tracking function:

    cvat-cli function create-native "SAM2" \
    --function-file=<CVAT_DIR>/ai-models/tracker/sam2/func.py \
    -p model_id=str:facebook/sam2.1-hiera-tiny
cvat-cli function run-agent <ID printed by previous command> \
    --function-file=<CVAT_DIR>/ai-models/tracker/sam2/func.py \
    -p model_id=str:facebook/sam2.1-hiera-tiny

These commands accept functions that implement the {{< ilink "/docs/api_sdk/sdk/auto-annotation" "auto-annotation function interface" >}} from the SDK, same as the task auto-annotate command. See that command's examples for information on how to implement these functions and specify them in the command line.

For detailed SAM2 setup instructions, see the {{< ilink "/docs/annotation/auto-annotation/segment-anything-2-tracker" "SAM2 Tracker documentation" >}}.

Delete

  • Delete functions with IDs 100 and 101: 
    cvat-cli function delete 100 101