Configuration

Configure authentication and server settings for CVAT CLI

The CVAT CLI requires configuration to connect to your CVAT server and authenticate requests. This page covers all configuration options.

Common Options

These options are available for all CLI commands and should be specified before the resource name.

Basic Syntax

cvat-cli [common options] <resource> <action> [action options]

Authentication

The CLI supports multiple authentication methods.

Username and Password

Provide credentials directly via the --auth option:

cvat-cli --auth username:password task ls

For security, you can omit the password and enter it when prompted:

cvat-cli --auth username task ls
Password for username at http://localhost: 

Environment Variables

Set credentials using environment variables to avoid typing them repeatedly.

Personal Access Token (Recommended)

Generate a Personal Access Token (PAT) from your CVAT account settings and set:

export CVAT_ACCESS_TOKEN="your-token-here"
cvat-cli task ls

Personal Access Tokens are more secure than passwords and can be easily revoked.

Password Environment Variable

Set the password in an environment variable:

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

Default Authentication

If no authentication is provided, the CLI:

1. Checks for CVAT_ACCESS_TOKEN environment variable
2. Falls back to the current system user and prompts for password

Server Configuration

Server Host

Specify the CVAT server URL:

cvat-cli --server-host http://localhost task ls

For remote servers:

cvat-cli --server-host https://cvat.example.com task ls

Default: http://localhost

Server Port

Specify a custom port:

cvat-cli --server-host http://cvat.example.com --server-port 8080 task ls

Defaults:

• Port 80 for HTTP connections
• Port 443 for HTTPS connections

Complete Server Example

cvat-cli --auth admin:password \
  --server-host cvat.my.server.com \
  --server-port 30123 \
  task ls

Organization Context

If your CVAT instance uses organizations, specify the organization slug:

cvat-cli --organization my-team task ls

Or use the short form:

cvat-cli --org my-team task ls

To explicitly use your personal workspace:

cvat-cli --organization "" task ls

Default behavior:

• When listing: shows all accessible objects across all organizations
• When creating: creates in your personal workspace

SSL Configuration

Disable SSL Verification

For self-signed certificates or testing environments:

cvat-cli --insecure --server-host https://localhost:8080 task ls

Only use --insecure with trusted servers. This option disables SSL certificate validation.

Debug Mode

Enable detailed logging for troubleshooting:

cvat-cli --debug task create "my-task" local image.jpg

Debug mode shows:

• HTTP request/response details
• Detailed error messages
• Timing information

Configuration Examples

Local Development

export CVAT_ACCESS_TOKEN="your-dev-token"
cvat-cli task ls

Remote Production Server

export CVAT_ACCESS_TOKEN="your-prod-token"
alias cvat-prod="cvat-cli --server-host https://cvat.company.com"
cvat-prod task ls

Custom Port with Organization

cvat-cli --auth user:pass \
  --server-host http://cvat.local \
  --server-port 8080 \
  --org team-name \
  task ls

Debug Connection Issues

cvat-cli --debug \
  --auth username \
  --server-host https://cvat.example.com \
  task ls

Configuration File

The CVAT CLI does not currently support a configuration file. All options must be provided via command-line arguments or environment variables.

Using Shell Aliases

Create shell aliases to simplify repeated commands:

# Add to ~/.bashrc or ~/.zshrc
export CVAT_ACCESS_TOKEN="your-token"
alias cvat="cvat-cli --server-host https://cvat.example.com"
alias cvat-dev="cvat-cli --server-host http://localhost:8080"

Then use:

cvat task ls
cvat-dev task create "test" local images/*.jpg

All Common Options

Option	Description	Default
--version	Show CLI version	-
--help	Show help message	-
--auth USER[:PASS]	Authentication credentials	Current user with prompt
--server-host HOST	CVAT server URL	http://localhost
--server-port PORT	Server port	80 (HTTP) or 443 (HTTPS)
--organization SLUG	Organization context	Personal workspace
--org SLUG	Short form of --organization	Personal workspace
--insecure	Disable SSL verification	false
--debug	Enable debug logging	false

Environment Variables

Variable	Purpose	Example
CVAT_ACCESS_TOKEN	Personal Access Token for auth	export CVAT_ACCESS_TOKEN="token123"
PASS	Password for username auth	export PASS="mypassword"

Next Steps

• Manage projects with CLI
• Work with tasks
• See complete workflow examples