CLI configuration

The CLI needs two values: the API key and the API address. It gets them from the configuration file, from environment variables, or from command options.

Configuration file

vidoc login writes the configuration file. The default location is:

Operating system	Path
macOS and Linux	`~/.vidoc/config.yaml`. If `XDG_CONFIG_HOME` is set: `$XDG_CONFIG_HOME/config.yaml`.
Windows	`%APPDATA%\Vidoc\config.yaml`

To use a different file, set VIDOC_CONFIG_FILE, or give -c <path> to vidoc scan, vidoc ci, or vidoc export. The file is YAML:

version: 1
current_profile: default
profiles:
  default:
    api_url: https://api.vidoc.dev
    token: <API key>
  self-hosted:
    api_url: https://api.<your-domain>
    token_env: VIDOC_TOKEN_SELF_HOSTED

Key	Meaning
`version`	The format version. Use `1`.
`current_profile`	The profile that the CLI uses when you do not select one.
`profiles.<name>.api_url`	The API address. Required. It must be a full URL, without a path.
`profiles.<name>.token`	The API key, as plain text.
`profiles.<name>.token_env`	The name of an environment variable that holds the API key.

Each profile must have token or token_env. If the file does not agree with this format, the CLI stops and shows the fields to fix.

Keep the key in an environment variable

vidoc login stores the key as plain text. To keep the key out of the file, use token_env:

Run vidoc config create-profile <name>.
For the storage of the key, select Environment Variable.
Type the name of the variable. The default is VIDOC_TOKEN_<NAME>.
Set the variable in your shell or your secret manager.

Profiles

A profile holds one API address and one API key. Use profiles when you work with more than one project or more than one Vidoc installation.

Command	Effect
`vidoc login <token> --profile <name>`	Create or replace a profile. Refer to Log in.
`vidoc config show`	Show the file path, the current profile, and all profiles. The CLI does not show the keys.
`vidoc config list-profiles`	List the profiles and their API addresses. Alias: `vidoc config profiles`.
`vidoc config set-profile <name>`	Make a profile the current profile.
`vidoc config create-profile <name>`	Create a profile. The CLI asks for the API address and the key.
`vidoc config delete-profile <name>`	Delete a profile. You cannot delete the `default` profile.

To use a profile for one command only, give -p <name> or set VIDOC_PROFILE:

vidoc scan -p self-hosted

Environment variables

Variable	Meaning
`VIDOC_TOKEN`	The API key. It overrides the key of the profile.
`VIDOC_API_URL`	The API address, for example `https://api.<your-domain>`. It overrides the address of the profile. Do not add `/v1`.
`VIDOC_PROFILE`	The profile to use.
`VIDOC_CONFIG_FILE`	The path of the configuration file.
`VIDOC_LOG_FILE`	The path of the log file. Default: `vidoc.log` in the current folder.
`DEBUG`	`true` or `1` turns on debug output, the same as `--debug`.
`CI`	`true` or `1` makes the CLI use the non-interactive mode.

In a CI pipeline, you can use VIDOC_TOKEN and VIDOC_API_URL without a configuration file.

Precedence

When a value has more than one source, the CLI uses the source that is highest in this table.

Value	1 (highest)	2	3	4 (lowest)
Profile	`-p`, `--profile`	`VIDOC_PROFILE`	`current_profile` in the file	`default`
API key	`--token`	`VIDOC_TOKEN`	`token_env` or `token` of the profile	none
API address	`--api-url`	`VIDOC_API_URL`	`api_url` of the profile	`https://api.vidoc.dev`
Configuration file	`-c`, `--config`	`VIDOC_CONFIG_FILE`	default path

If the configuration file exists and does not have the selected profile, the CLI stops with the error Profile "<name>" not found in config file.

Self-hosted: if no source sets the API address, the CLI uses the Vidoc Cloud API https://api.vidoc.dev. Always set the address of your installation, in the profile or in VIDOC_API_URL.

Install and log in

Install the CLI and create an API key.

CI/CD pipelines

Use environment variables in CI.

Get started

Deployment

Integrations

Pull request reviews

Web app

CLI

API reference

Reference

CLI configuration

Configuration file

Keep the key in an environment variable

Profiles

Environment variables

Precedence

Install and log in

CI/CD pipelines

​Configuration file

​Keep the key in an environment variable

​Profiles

​Environment variables

​Precedence

​Related pages

Install and log in

CI/CD pipelines

Configuration file

Keep the key in an environment variable

Profiles

Environment variables

Precedence

Related pages