CLI configuration file - Incus documentation
Description: The Incus CLI client uses a configuration file to store environment data and modify its behavior. This documentation describes the file structure and its options. The configuration file: By default...

Skip to content
Back to top
View this page

# CLI configuration file

The Incus CLI client uses a configuration file to store environment data and modify its behavior. This documentation describes the file structure and its options.

Note

Changing this configuration file manually may leave the CLI in an inconsistent state, so you should only edit it via CLI commands such as `incus remote` and `incus alias`.

## The configuration file

By default, the Incus CLI will use the `$HOME/.config/incus/config.yml`, but it can also use the `config.yml` in an arbitrary directory provided by the `INCUS_CONF` environment variable.

If the file or its path don’t exist, it will use the default:

    default-remote: local
    remotes:
      images:
        protocol: simplestreams
        public: true
        addr: https://images.linuxcontainers.org
      local:
        protocol: incus
        public: false
        addr: unix://
    aliases: {}
    defaults:
      list_format: ""
      console_type: ""
      console_spice_command: ""
      no_color: false

## `remotes`

Incus remote information managed by `incus remote` commands is stored in the `remotes` section. Remotes may have the following configuration keys.

### `addr`

Address of the remote server. Accepts IPs, FQDNs and URLs. Multiple addresses can be provided, separated with commas `addr1,addr2,...`.

### `last_working_address`

Used by the CLI to register the last working address of a remote, if the remote has multiple addresses.

### `auth_type`

Method that the client will use to authenticate to the server API. Accepts `tls` and `oidc`.

### `keepalive`

Timeout in seconds that the `keepalive` feature will maintain the connection opened.

### `project`

Default project used by the CLI when using that remote. It’s defined by the `incus project switch` command. It’s overwritten by the `--project` flag and the `INCUS_PROJECT` environment variable.

### `protocol`

The protocol the CLI will use to communicate with the remote. This defines if the remote will be used as an Incus or image server. Accepts the following options:

- `incus`: private Incus server accessible over the network

- `oci`: Open Container Initiative (OCI) server that provides application container images

- `public`: Incus server accessible over the network to provide images only

- `simplestream`: Simple Stream server that provide images

### `credentials_helper`

Defines a helper command that will handle OCI service authentication.

### `public`

Defines if the remote is an image-only server (public).

## `default_remotes`

Defines the default Incus remote used by the CLI to execute commands. It’s defined by the `incus remote switch` command. This configuration is overwritten by the environment variable `INCUS_REMOTE` or by the `<remote>:` prefix.

## `aliases`

Stores the alias managed by the `incus alias` command. Each alias is a key/value pair that consists of the alias name and the alias command (enclosed by quotes).

## `defaults`

Determines the default CLI behavior for certain CLI commands.

### `list_format`

Defines how list outputs will be displayed. Equivalent to the `--format` (`-f`) flag. Accepts `csv`, `json`, `table`, `yaml`, `compact` and `markdown` formats.

### `console_type`

Defines the default console type used by the `incus console` command. Available options are:

- `console`: text based console

- `vga`: graphic UI console

### `console_spice_command`

Defines an alternative SPICE command to provide the VGA console used by `incus console`.

### `no_color`

Disables CLI colors.