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:** If you work with just one project, the default configuration, named `default`, should be 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/gdcag/resources/gdcloud-manage-properties.md.txt).

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/gdcag/resources/gdcloud-manage-configurations.md.txt#activate-config).

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

## Default configuration

The gdcloud CLI initially creates a single configuration named
`default`. You can set properties in your configuration by running the `gdcloud
init` command or by running `gdcloud config set` directly.

## 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`. The initial `default`
configuration is created as a convenience, and is not required to use. You can
name this and any additional configurations however you'd 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:

```bash
gdcloud config configurations create NAME
```

You must [activate](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-manage-configurations.md.txt#activate-config) the new configuration after creation 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 will govern the
behavior of the gdcloud CLI.

To activate a new configuration or switch to a new active configuration, run:

```bash
gdcloud config configurations activate NAME
```

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

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

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

## List configurations

To list the configurations in your gdcloud CLI, run:

```bash
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:

```bash
gdcloud config set project PROJECT
```

## Viewing configuration properties

To view the properties in a configuration, run:

```bash
gdcloud config configurations describe NAME
```

The gdcloud CLI prints the configuration properties:

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

To view properties in the active configuration, run:

```bash
gdcloud config list
```

## Delete a configuration

To delete a configuration, run:

```bash
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.