> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidocsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI configuration

> Configuration file, profiles, environment variables, and the order in which the Vidoc CLI applies them.

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:

```yaml theme={null}
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`:

1. Run `vidoc config create-profile <name>`.
2. For the storage of the key, select **Environment Variable**.
3. Type the name of the variable. The default is `VIDOC_TOKEN_<NAME>`.
4. 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](/cli/installation#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`:

```bash theme={null}
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](/cli/scanning#interactive-and-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`.

<Note>
  **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`.
</Note>

## Related pages

<CardGroup cols={2}>
  <Card title="Install and log in" icon="download" href="/cli/installation">
    Install the CLI and create an API key.
  </Card>

  <Card title="CI/CD pipelines" icon="gear" href="/cli/ci-cd">
    Use environment variables in CI.
  </Card>
</CardGroup>