A configuration is a named set of Distributed Cloud CLI properties. These
properties are key-value pairs, organized in sections, that govern the behavior
of the gdcloud CLI.

> [!TIP]
> **Tip:** Usually, if you work with just one project, the default configuration named `default` is sufficient. To learn more about setting properties in a configuration to define per-organization or per-project settings such as the organization console URL or project to use, accessibility preferences, see [Manage properties](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/resources/gdcloud-manage-properties).

Properties that are commonly stored in configurations include the organization
console URL and project ID. Configurations allow you to define and enable these
and other settings together as a group.

Configurations are stored in your user config directory, typically
`~/.config/gdcloud` on Linux, `$HOME/Library/Application Support/gdcloud` on
Mac, and `%AppData%\gdcloud` on Windows. Also, note that the config directory
must be write-enabled.

If you have multiple configurations, you can choose to switch between them, or
run commands using a specific configuration with the
`--configuration` flag. For more about switching configurations, refer to the
section on [Activate a configuration](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/resources/gdcloud-manage-configurations#activate-config).

To read about configurations from the command line along with a complete list of
available properties and the sections they are in, run `gdcloud topic
configurations`.

## Default configuration

The gdcloud CLI starts you off with a single configuration named
`default`. To set properties in your configuration, run either the `gdcloud
init` or `gdcloud config set` command.

## Multiple configurations

The single `default` configuration is suitable for many use cases. However, you
can also create additional configurations and switch between them as required
using `gdcloud config configurations activate`. There is nothing special about
the initial `default` configuration; it is created as a convenience. You can
name this and any additional configurations however you like.

Multiple configurations are useful if you want to:

- **Use multiple projects**: You can create a separate configuration for each project and switch between them as required.
- **Use multiple organization console URLs**.
- **Perform generally independent tasks**: For example, you can use one configuration to work on service A in one project and manage an unrelated service B in another project.

## Create a configuration

To create a configuration, run `gdcloud config configurations create`:

    gdcloud config configurations create NAME

You must [activate](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/resources/gdcloud-manage-configurations#activate-config) the new configuration after creation in
order to use it.

## Activate a configuration

Only one of your multiple configurations can be active at a given time. The
active configuration is the configuration whose properties govern the behavior
of the gdcloud CLI.

To activate a new configuration or switch to a new active configuration, run:
`gdcloud config configurations activate`:

    gdcloud config configurations activate NAME

`gdcloud config list` always shows you the properties in your active
configuration.

To change the active configuration for a single command invocation, you can use
the `--configuration` flag for any gdcloud CLI command:

    gdcloud auth print-identity-token --configuration=CONFIGURATION

## List configurations

To list the configurations in your gdcloud CLI, run:

    gdcloud config configurations list

The gdcloud CLI lists the configurations and shows which
configuration is active:

    NAME                ISACTIVE   PROPERTIES.CORE.PROJECT PROPERTIES.CORE.ORGANIZATIONCONSOLEURL
    default             False      example-project-default https://console.default-org.example.com
    config-project-1    False      example-project-1       https://console.org-1.example.com
    config-project-2    False      example-project-2       https://console.org-2.example.com

## Setting configuration properties

To set and unset the properties in the active configuration, run:

    gdcloud config set project PROJECT

## Viewing configuration properties

To view the properties in a configuration, run:

    gdcloud config configurations describe NAME

The gdcloud CLI prints the configuration properties:

    is_active: false
    name: default
    properties:
      accessibility:
        screen_reader: "false"
      auth:
        insecure_skip_tls_verify: "false"
      core:
        organization_console_url: https://console.example.com
        project: example-project

To view properties in the active configuration, run:

    gdcloud config list

## Delete a configuration

To delete a configuration, run:

    gdcloud config configurations delete NAME

You can't delete an active configuration. To switch to another configuration
before deleting, use `gdcloud config configurations activate` if required.