企业官网建设流程全解析

CVAT CLI 命令行工具完全指南：安装、认证、任务/项目/函数管理与自动标注实战

【免费下载链接】cvatComputer Vision Annotation Tool (CVAT) is a leading platform for building high-quality visual datasets for vision AI. It offers open-source, cloud, and enterprise products, as well as labeling services, for image, video, and 3D annotation with AI-assisted labeling, quality assurance, team collaboration, analytics, and developer APIs.项目地址: https://gitcode.com/GitHub_Trending/cvat/cvat

导读

CVAT（Computer Vision Annotation Tool）提供了一个名为cvat-cli的命令行客户端，用于在终端中直接管理 CVAT 服务器上的项目、任务和（Enterprise/Cloud 版）AI 函数资源。本文以官方 CLI 文档为主线，结合仓库中 cvat-cli 源码 与 cvat-sdk 认证实现，系统讲解安装方式、通用命令结构、两种认证方案与持久化 profile 机制，并逐一演示任务、项目、函数的完整实操命令。读完本文，你将掌握用一行命令完成"建任务→传数据→自动标注→导出数据集→备份恢复"全流程的能力。

Overview：CLI 能做什么

CVAT CLI 是一个"简单但可扩展"的命令行界面，目前实现了基础功能集，未来可以发展为更全面的 CVAT 管理工具。它围绕三类资源组织子命令：

• Projects（项目）：backup、create、create-from-backup、delete、export-dataset、import-dataset、ls
• Tasks（任务）：create、create-from-backup、delete、ls、frames、export-dataset、import-dataset、backup、auto-annotate
• Functions（函数，仅 Enterprise/Cloud）：create-native、delete、run-agent

在源码中，这些命令分别定义于 commands_tasks.py、commands_projects.py 与 commands_functions.py，统一由 command_base.py 中的CommandGroup机制注册：每个命令是一个实现了description/configure_parser/execute协议的类，通过@COMMANDS.command_class("name")装饰器挂载到 argparse 子命令树上（command_base.py）。

安装

CVAT CLI 作为独立 Python 包发布，一条命令即可安装：

pip install cvat-cli

• Python 版本要求：3.10 及以上（见 pyproject.toml 中requires-python = ">=3.10"）。
• 安装后提供cvat-cli可执行入口，由 pyproject.toml 中cvat-cli = "cvat_cli.__main__:main"指定，最终调用main.py 中的main()完成参数解析、客户端构建与执行。
• 依赖项：cvat-sdk（固定版本）、attrs、json-with-comments（用于解析 profile token 信封文件）、Pillow（见 pyproject.toml）。

通用用法与命令结构

所有命令遵循统一形态：

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

其中：

• <common options>：所有子命令共享的全局选项（认证、服务器地址、组织等）；
• <resource>：CVAT 资源类型，如task、project、function；
• <action>：对资源执行的动作，如create、ls、delete；
• <options>：特定资源与动作专属的参数。

三个层级的--help由浅入深：

$ cvat-cli --help # 查看公共选项与可用资源 $ cvat-cli <resource> --help # 查看某资源的可用动作 $ cvat-cli <resource> <action> --help # 查看动作专属参数

公共选项（在 auth.py 的configure_client_auth_arguments中定义）主要包括：

另外，部分任务动作提供了别名子命令用于向后兼容，例如cvat-cli ls等价于cvat-cli task ls。这些别名已被标记为弃用（deprecated），执行时会输出警告，建议始终使用task <action>形式（command_base.py）。

认证

CLI 支持两种认证方式：

1. Personal Access Token（PAT）认证：使用访问令牌，令牌可在 CVAT UI 的用户设置中创建，是推荐的首选认证方式（参见 访问令牌文档）。
2. 密码认证：使用用户名 + 密码组合，为安全起见，如可能建议优先使用 PAT。

PAT 认证

PAT 只能通过CVAT_ACCESS_TOKEN环境变量使用，且该变量优先级高于其他认证环境变量：

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

在源码层面，default_auth_factory()会优先读取CVAT_ACCESS_TOKEN环境变量构造令牌凭据，未设置时才回退到系统用户名 + 密码询问流程（auth.py）。

密码认证

凭据通过全局参数--auth指定，密码可以跟在冒号（:）分隔符后，也可通过PASS环境变量提供：

cvat-cli --auth "username:password" task ls

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

--auth也可以省略：此时 CLI 尝试使用当前 OS 用户作为用户名；若配置了PASS环境变量则作为密码，否则交互式请求输入密码：

cvat-cli task ls

get_auth_factory()的实现正是这个逻辑：解析USER[:PASS]，缺密码时先查PASS环境变量，再不行就getpass交互提示（auth.py）。

持久化认证（Profiles）

为避免每天重复输入--server-host/--auth或让凭据泄漏进 shell 历史，CLI 可以把服务器地址与 PAT 保存在本地"profile"中。每个 profile 自包含：一个服务器 + 一个 PAT。

存储位置与权限

Profiles 以 JSON 文件形式存储，位于0700权限目录下、文件本身为0600模式（仅属主可读写）。CLI 会拒绝读写文件或其父目录可被组/他人访问的情况（Windows 上为尽力检查）。位置遵循平台惯例：

该路径由get_auth_store_path()基于platformdirs.user_config_path计算（auth.py），读写由AuthStore类强制执行0600/0700权限检查（auth.py）。

注意：本地 profile 仅支持 PAT 认证方式，用户名/密码无法以这种方式记忆。

管理 Profiles

使用cvat-cli profile与cvat-cli config创建和管理 profile。这些命令只操作本地文件、不与服务器通信（唯一的例外是：当未提供令牌名称时，profile create会向服务器查询令牌的name）。

# 保存一个 profile；省略令牌时交互式输入（不回显） cvat-cli --server-host https://app.cvat.ai profile create --name mycvat --set-default # 直接粘贴令牌保存，并指定昵称 cvat-cli --server-host https://app.cvat.ai profile create --name mycvat "<paste-token-here>" # 从纯文本文件导入令牌 cvat-cli --server-host https://app.cvat.ai profile create --name mycvat --file ~/Downloads/cvat-token.txt # JSONC 信封文件（含令牌、服务器、profile 名），无需额外参数 cvat-cli profile create --file ~/Downloads/cvat-token-my-laptop.json # 查看与管理存储 cvat-cli profile list # 列出名称、服务器与默认标记 cvat-cli profile list --names-only # 仅名称，一行一个（脚本友好） cvat-cli profile default # 打印当前默认 profile cvat-cli profile default staging # 将 "staging" 设为默认 cvat-cli profile default --unset # 取消默认 cvat-cli profile delete staging # 删除 profile（不会吊销令牌） # 设置默认服务器（当既无 --server-host 也无 --profile 时作为后备） cvat-cli config default-server https://app.cvat.ai cvat-cli config default-server # 打印当前默认服务器 cvat-cli config default-server --unset

令牌信封文件支持 JSONC 语法（含注释、尾随逗号）。如果下载信封后服务器地址有变更，可用--server-host覆盖信封内嵌的服务器 URL：

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

删除 profile 不会吊销服务器端令牌；如需吊销请到 CVAT UI 或通过 API 操作。源码中ProfileCreate.execute完整实现了上述逻辑：支持--name、--set-default、--force覆盖、--file导入、交互式getpass输入令牌等（commands_profile.py）。

单条命令选择 Profile

全局--profile <name>标志为单条命令选择已保存的 profile，它与--server-host、--server-port、--auth互斥：

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

解析顺序

CLI 首先尝试选择 profile：

1. 显式指定--profile NAME：同时提供服务器与 PAT，不能与--server-host、--server-port、--auth组合使用。
2. 否则，若配置了默认 profile 且未显式提供服务器或凭据，则使用默认 profile（CVAT_ACCESS_TOKEN被视为显式凭据）。

若选中 profile，则服务器与凭据都由它提供、解析终止。否则凭据与服务器各自独立解析：

凭据解析顺序：

1. --auth USER[:PASS]（省略 PASS 时用PASS环境变量或交互询问）；
2. CVAT_ACCESS_TOKEN（若已设置）；
3. 当前 OS 用户名 +PASS环境变量或密码询问。

服务器解析顺序：

1. --server-host（--server-port作用于选定的主机；若只给--server-port，主机来自下面的来源）；
2. cvat-cli config default-server配置的服务器（若已设置）；
3. 内置默认值http://localhost（源码常量DEFAULT_SERVER，见 auth.py）。

提供显式凭据或服务器会阻止 CLI 从默认 profile 借用另一项值。

任务（Task）实战示例

创建任务

创建任务需要一份 JSON 格式的标签（labels）文件，可以借助 UI 中的标签构造器生成。示例 labels.json：

[ { "name": "cat", "attributes": [] }, { "name": "dog", "attributes": [] } ]

在源码中--labels参数由parse_label_arg()解析：如果传的是已存在路径则按 JSON 文件读取，否则按 JSON 字符串解析（parsers.py），因此两种写法均可。

基础示例：在默认服务器http://localhost上创建名为 "new task" 的任务，标签来自 "labels.json"，数据为本地图片 "file1.jpg"、"file2.jpg"，任务以当前用户创建：

cvat-cli task create "new task" --labels labels.json local file1.jpg file2.jpg

指定服务器与用户：在https://example.com上创建 "task 1"，标签来自 "labels.json"，本地图片 "image1.jpg"，以用户 "user-1" 创建：

cvat-cli --server-host https://example.com --auth user-1 task create "task 1" \ --labels labels.json local image1.jpg

指定组织：在默认服务器创建 "task 1"，标签来自 "labels.json"，本地图片 "file1.jpg"，当前用户身份，组织 "myorg"：

cvat-cli --org myorg task create "task 1" --labels labels.json local file1.jpg

继承项目标签 + 远程视频：标签来自 id 为 1 的项目，数据为远程视频文件，以用户 "user-1" 创建：

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

高级参数组合：标签 "cat"、"dog"，chunk 大小 8，随机排序，帧步长 10，复制数据到 CVAT 服务器，使用 zip chunks，视频来自共享资源：

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

带标注导入与质量设置：标签来自 "labels.json"，链接 bug tracker，图片质量降至 75，从 "annotation.xml" 导入 "CVAT 1.1" 格式标注，数据来自 "dataset_1/images/"，以 "user-2" 创建（密码需另行输入）：

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/

分段（segment）参数：overlay 大小 5，segment 大小 100，第 5 到 705 帧，使用缓存，远程视频：

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

云存储数据过滤：使用test_images/*.jpeg过滤 manifest.jsonl 中描述的云存储数据：

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

使用全部云存储数据（filename_pattern为*）：

cvat-cli task create "task with filtered cloud storage data" --labels '[{"name": "car"}]'\ --use_cache --cloud_storage_id 1 --filename_pattern "*" share manifest.jsonl

task create支持的全部参数（含默认值）可在 commands_tasks.py 中查看，常用参数包括：

从实现上看，TaskCreate.execute会把 kwargs 按models.DataRequest.attribute_map拆分为data_params与task_params，随后调用client.tasks.create_from_data(...)一次性完成"建任务 + 传数据 + 可选导入标注"，成功后打印新任务 ID（commands_tasks.py）。

删除任务

删除 ID 为 100、101、102 的任务，以拥有删除权限的 "user-1" 执行：

cvat-cli --auth user-1:password task delete 100 101 102

底层由GenericDeleteCommand的remove_by_ids实现，会忽略不存在的 ID（command_base.py）。

列出任务

cvat-cli task ls # 列出全部任务 cvat-cli --org myorg task ls # 列出组织 "myorg" 的全部任务 cvat-cli task ls --json > list_of_tasks.json # 以 JSON 格式保存到文件

--json输出使用缩进美化后的 JSON；不加--json时默认只打印任务 ID 列表（command_base.py）。

下载帧

将任务 119 的第 12、15、22 帧以压缩质量保存到 "images" 文件夹：

cvat-cli task frames --outdir images --quality compressed 119 12 15 22

• --quality可选original（默认）或compressed；
• 默认输出到当前目录（--outdir为空时）；
• 保存的文件名模式为task_<ID>_frame_<FRAME>.jpg（commands_tasks.py）。

导出数据集

cvat-cli task export-dataset --format "CVAT for images 1.1" 103 output.zip # 导出任务 103 为 CVAT 格式 cvat-cli task export-dataset --format "COCO 1.0" 104 output.zip # 导出任务 104 为 COCO 格式

导出的默认格式为CVAT for images 1.1；--with-images控制是否包含图片（默认False，项目导出示例中会用到）；省略输出文件名时保存到当前目录并使用服务器生成的名称（command_base.py）。

从数据集导入标注

将任务 105 以CVAT 1.1格式从 "annotation.xml" 导入标注：

cvat-cli task import-dataset --format "CVAT 1.1" 105 annotation.xml

备份任务

将任务 136 备份到 "task_136.zip"：

cvat-cli task backup 136 task_136.zip

从备份创建任务

从备份文件 "task_backup.zip" 创建任务：

cvat-cli task create-from-backup task_backup.zip

自动标注（Auto-annotate）

task auto-annotate是自动标注 API 的命令行入口，它在本机运行 AA 函数对指定任务进行自动标注。AA 函数可通过以下两种方式实现：

方式一：模块级直接实现 AA 函数协议。模块顶层必须定义所需属性：

import cvat_sdk.auto_annotation as cvataa spec = cvataa.DetectionFunctionSpec(...) def detect(context, image): ...

方式二：实现名为create的工厂函数。该函数返回一个实现 AA 函数协议的对象，命令行中用-p指定的参数会传给create：

import cvat_sdk.auto_annotation as cvataa class _MyFunction: def __init__(...): ... spec = cvataa.DetectionFunctionSpec(...) def detect(context, image): ... def create(...) -> cvataa.DetectionFunction: return _MyFunction(...)

示例一：用预置的 torchvision 检测函数（带参数）标注任务 137：

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

示例二：用my_func.py中定义的 AA 函数标注任务 138：

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

注意：该命令不会修改 Python 模块搜索路径。如果函数模块需要导入其他本地模块，必须确保其目录已在搜索路径中。

示例三：函数定义在my-project目录的my_func模块中，允许它从该目录导入其他模块：

PYTHONPATH=path/to/my-project cvat-cli task auto-annotate 139 --function-module my_func

参数格式：-p的格式为NAME=TYPE:VALUE，支持int、float、str、bool四种类型，由parse_function_parameter()解析（parsers.py）。--function-module与--function-file二选一必填，二者由configure_function_implementation_arguments构造互斥组（common.py）。函数加载由FunctionLoader.load()完成：模块方式用importlib.import_module，文件方式用spec_from_file_location动态加载；若函数对象有create属性则视为工厂并传入参数调用，且要求最终对象必须带spec属性（common.py）。

task auto-annotate还支持以下选项（commands_tasks.py）：

仓库自带的预置函数位于 auto_annotation/functions 目录，包括torchvision_detection、torchvision_classification、torchvision_instance_segmentation、torchvision_keypoint_detection等。以torchvision_detection为例，其detect方法会读取context.conf_threshold过滤低置信度框，并生成矩形标注（torchvision_detection.py）。

项目（Project）实战示例

创建项目

创建项目时可选定义标签，project create的--labels与task create格式相同（参见上文任务示例）。

基础示例：在默认服务器http://localhost创建 "new project"，标签来自 "labels.json"：

cvat-cli project create "new project" --labels labels.json

从数据集创建（COCO 格式）：

cvat-cli project create "new project" --dataset_path coco.zip --dataset_format "COCO 1.0"

从数据集创建并每秒检查导入状态：

cvat-cli project create "new project" --dataset_path coco.zip --dataset_format "COCO 1.0" \ --completion_verification_period 1

实现上，ProjectCreate.execute调用client.projects.create_from_dataset(...)，其中--dataset_path与--dataset_format（默认CVAT 1.1）仅在指定数据集路径时生效（commands_projects.py）。

删除项目

cvat-cli project delete 100 101 102

列出项目

cvat-cli project ls # 列出全部项目 cvat-cli project ls --json > list_of_projects.json # 保存为 JSON

备份项目

cvat-cli project backup 25 project_25.zip

从备份创建项目

cvat-cli project create-from-backup project_backup.zip

导出数据集

cvat-cli project export-dataset --format "CVAT for images 1.1" 103 project.zip # 导出项目 103 cvat-cli project export-dataset --format "COCO 1.0" --with-images yes 104 project.zip # COCO 格式并包含图片 cvat-cli project export-dataset --format "CVAT for images 1.1" 105 # 保存到当前目录，使用服务器生成文件名

--with-images接受布尔值（如yes/no），由to_bool转换（command_base.py）。

从数据集创建任务

为项目 106 从 "coco.zip"（COCO 1.0格式）创建任务：

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

前提条件：项目必须拥有与导入数据集兼容的标签；上传的数据集必须包含图像数据，因为该命令会创建带图像和标注的新任务（与task import-dataset仅导入标注不同，project import-dataset同时创建任务并导入图像与标注，见 commands_projects.py）。

函数（Function）实战示例（仅 Enterprise/Cloud）

注意：本节功能只能在 CVAT Enterprise 或 CVAT Cloud 中使用。

函数相关命令接受与task auto-annotate相同的 AA 函数（即实现 SDK 的自动标注函数接口），因此实现方式与--function-module/--function-file/-p的用法与上文一致。

创建并使用 torchvision 检测函数

创建使用 torchvision 检测模型的函数，并为其运行 agent：

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

其中第一条命令会打印新函数的 ID，run-agent需要用到它。create-native支持--visibility private|public（默认private），并在服务端/api/functions端点注册provider=native的函数（commands_functions.py）。

创建并运行 SAM2 追踪函数

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

这里的<CVAT_DIR>指 CVAT 源码仓库目录，ai-models/tracker/sam2/func.py即仓库中的 SAM2 追踪 AA 函数实现。关于 SAM2 的详细部署与使用说明，参见 SAM2 Tracker 文档（AI Agent 变体可通过 AA 函数在用户侧运行，为 CVAT Online 与 Enterprise 带来 SAM2 追踪能力，且推荐使用 GPU 以获得性能）。

删除函数

cvat-cli function delete 100 101

function delete会逐个删除函数，404 时给出警告，其他失败打印错误（commands_functions.py）。

小结

• 命令模型统一：cvat-cli <common> <resource> <action> <options>，三级--help可随时查阅全部参数。
• 认证首选 PAT：通过CVAT_ACCESS_TOKEN环境变量注入，或使用profile/config持久化服务器与令牌，避免凭据进入 shell 历史；--profile提供单命令级的快速切换。
• 全生命周期覆盖：任务与项目均支持创建、列表、删除、备份/恢复、数据集导入导出；任务还支持帧下载与本地 AA 函数自动标注。
• 自动标注体系：task auto-annotate（即时模式）与function create-native+run-agent（agent 模式，Enterprise/Cloud）共用同一套 AA 函数协议，仓库预置了多个 torchvision 函数，并支持通过-p NAME=TYPE:VALUE参数化。

如需继续深入，可阅读仓库中的 cvat-cli 源码、cvat-cli 包说明、自动标注 API 文档 与访问令牌文档。

【免费下载链接】cvatComputer Vision Annotation Tool (CVAT) is a leading platform for building high-quality visual datasets for vision AI. It offers open-source, cloud, and enterprise products, as well as labeling services, for image, video, and 3D annotation with AI-assisted labeling, quality assurance, team collaboration, analytics, and developer APIs.项目地址: https://gitcode.com/GitHub_Trending/cvat/cvat