> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/configure-client-profiles/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure client profiles

Gateway 5.4+

Client profiles let you define named connection configurations in `gateway.conf` and switch between them using the `--profile` flag — without editing the config file or setting environment variables between commands. Use profiles when you manage multiple gateway clusters, such as production, staging, and development environments, from a single workstation.

## Define profiles in gateway.conf

Profiles are defined as `[client:profile_name]` sections in `gateway.conf`. Each profile inherits any settings not explicitly defined from the base `[client]` section, so you only need to specify values that differ from the base configuration.

Profile sections support the following properties:

| Property           | Description                           |
| ------------------ | ------------------------------------- |
| `host`             | Gateway hostname or IP address        |
| `port`             | Gateway port number                   |
| `api_key`          | API key for authentication            |
| `certificate_file` | Path to the client certificate file   |
| `private_key_file` | Path to the client private key file   |
| `use_tls`          | Whether to use TLS for the connection |

Profile names are alphanumeric, case-insensitive, and normalized to lowercase internally — `production`, `Production`, and `PRODUCTION` all resolve to the same profile.

```ini
[client]
host = localhost
port = 50051

[client:production]
host = gw.prod.example.com
certificate_file = ~/.gateway.d/certs/prod.crt
private_key_file  = ~/.gateway.d/certs/prod.key

[client:staging]
host = gw.staging.example.com
```

In this example, the `staging` profile inherits `port = 50051` from the base `[client]` section and only overrides `host`. The `production` profile overrides `host` and specifies its own certificate files.

## Use a profile

Pass `--profile <profile_name>` to any `iagctl` command to use a named profile:

```bash
# Uses [client] section (localhost)
iagctl get services

# Uses [client:production]
iagctl --profile production get services

# Uses [client:staging]
iagctl --profile staging get services
```

Without `--profile`, `iagctl` uses the base `[client]` section as before — existing configurations require no changes.

## Override profile settings with environment variables

You can override individual profile settings using environment variables following the pattern `GATEWAY_CLIENT_<PROFILE>_<SETTING>`, where `<PROFILE>` is the uppercase profile name and `<SETTING>` is the uppercase setting name.

For example, to override the host for the `production` profile:

```bash
export GATEWAY_CLIENT_PRODUCTION_HOST=gw.prod-us-east.example.com
iagctl --profile production get services
```

Profile-specific environment variables take precedence over all other configuration sources. The full precedence order for any setting is:

1. Profile-specific environment variable (`GATEWAY_CLIENT_<PROFILE>_<SETTING>`)
2. Profile config section (`[client:profile_name]`)
3. Base environment variable (`GATEWAY_CLIENT_<SETTING>`)
4. Base config section (`[client]`)
5. Default value

## Verify the active configuration

Run `iagctl version --show-config` to display the resolved effective configuration after profile selection:

```bash
iagctl --profile production version --show-config
```

The output reflects the fully resolved configuration — inherited values from the base `[client]` section, overrides from the profile section, and any environment variable overrides applied on top.

## Learn more

* [Client variables](./gateway-client-variables)
* [Configure gateway client](./client-configuration)