---
title: "Profiles and configuration"
description: "Keep separate ezgh logins and default settings in profiles, and configure ezgh with flags, environment variables and config.toml."
---

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

# Profiles and configuration

A profile is one way of using EZGH Cloud: its own [credential](/cli/authentication) and its own default organization, project and output format. Use profiles to keep two accounts, or a person and a CI bot, side by side. Without any setup, `ezgh` uses the built-in profile `default`.

## Create and use profiles

```sh
ezgh login --profile work
ezgh auth set-api-key --profile ci < ci-key.txt
ezgh profiles use work
ezgh profiles list
```

```text
    NAME      DOMAIN          IDENTITY        CREDENTIAL   STATUS
    ci        ezghcloud.com   ezgh_Ab3dE6…    apiKey       valid
    default   ezghcloud.com   -               -            not logged in
*   work      ezghcloud.com   ada@acme.test   oauth        valid
```

- `ezgh login` and `ezgh auth set-api-key` create the profile if it doesn't exist.
- `ezgh profiles create <name>` creates a profile without a credential. Pass `--org`, `--project` and `-o` to store its settings, and `--use` to make it the default.
- `ezgh profiles use <name>` makes a profile the default.
- `ezgh profiles rename <old> <new>` renames a profile and moves its credential.
- `ezgh profiles delete <name>` logs the profile out, revoking its login, and removes its settings and stored credential. It asks for confirmation, or takes `--yes`.

Profile names are 1 to 64 letters, digits, `-` and `_`, starting with a letter or digit.

> **Caution**
>
> Don't name a profile `local`. That name is reserved: a profile named `local` doesn't use `ezghcloud.com` unless you set its `domain`.

### Profile status

`ezgh profiles list` checks each profile's credential with the platform, in parallel, and marks the active profile with `*`. `--no-check` skips the checks. `EZGH_API_KEY` isn't used: each profile shows its own credential.

| Status | Meaning |
| --- | --- |
| `valid` | The platform accepted the credential |
| `invalid` | The platform refused it: expired, revoked, or not valid |
| `not logged in` | The profile has no credential |
| `unreachable` | The platform couldn't be reached |
| `unchecked` | Not checked (`--no-check`) |
| `unreadable` | The stored credential couldn't be read |

## Choose a profile

Commands use the first of:

1. The `--profile` flag.
2. The `EZGH_PROFILE` environment variable.
3. The default profile, set with `ezgh profiles use`.
4. The built-in profile `default`.

Only `ezgh login`, `ezgh auth set-api-key` and `ezgh config set` accept a profile that doesn't exist yet, and create it. Other commands refuse it with exit code `2`, so a mistyped name never runs without a credential. `ezgh auth status` and `ezgh whoami` show the active profile and where the choice came from.

## Settings

Each profile has these settings. A flag takes precedence over its environment variable, which takes precedence over the profile's setting, which takes precedence over the default.

| Setting | Flag | Environment variable | Default |
| --- | --- | --- | --- |
| `organization` | `--org` | `EZGH_ORG` | The only organization you belong to |
| `project` | `--project` | `EZGH_PROJECT` | None |
| `output` | `-o`, `--output` | None | `table` |
| `domain` | None | `EZGH_DOMAIN` | `ezghcloud.com` |

- **organization** is an ID or slug (`org_k3f9a0x2m7qp`). You rarely need it: without it, `ezgh` uses the organization you belong to. If you don't belong to one yet, commands that need it fail and say so.
- **project** is an ID, slug or name. Commands that work in a project, such as `ezgh ocr processors list`, fail when none is given. `ezgh projects get`, `update` and `delete` use it when you don't name a project.
- **output** is `table`, `json` or `yaml`. See [Output](/cli#output).
- **domain** is the platform's domain. A profile's credential belongs to its domain: after changing it, log in again.

Change the active profile's settings with `ezgh config`:

```sh
ezgh config set project web
ezgh --profile ci config set output json
ezgh config get project
ezgh config unset project
ezgh config list
```

`ezgh config set`, `get` and `unset` take `organization` (or `org`), `project`, `output` and `domain`. `ezgh config get` prints the value stored in the profile, or the default. `ezgh config list` prints the values commands run with, including flags and environment variables, and where each comes from:

```text
KEY            VALUE              SOURCE
profile        default            built-in
domain         ezghcloud.com      built-in
organization   org_k3f9a0x2m7qp   flag --org
project        web                profile
output         table              built-in
```

## Configuration file

Settings are stored in `config.toml`, which `ezgh config` and `ezgh profiles` write, readable only by you:

```toml
default_profile = "work"

[profiles.work]
organization = "org_k3f9a0x2m7qp"
project = "web"
output = "table"

[profiles.ci]
output = "json"
```

| Key | Meaning |
| --- | --- |
| `default_profile` | The default profile (`ezgh profiles use`) |
| `[profiles.<name>]` | A profile, with `organization`, `project`, `output` and `domain` |

An unknown key in the file is an error, so a mistyped setting never goes unnoticed. Credentials are never stored in `config.toml`.

### Configuration directory

`config.toml` is in the first of:

1. `EZGH_CONFIG_DIR`, when it's set.
2. `$XDG_CONFIG_HOME/ezgh`, when `XDG_CONFIG_HOME` is set to an absolute path (macOS and Linux).
3. The system's configuration directory:

| System | Directory |
| --- | --- |
| macOS | `~/Library/Application Support/ezgh` |
| Linux | `~/.config/ezgh` |
| Windows | `%AppData%\ezgh` |

The same directory holds `credentials.json` when credentials can't go in the system keychain. See [Where credentials are stored](/cli/authentication#where-credentials-are-stored).

## Environment variables

| Variable | Effect |
| --- | --- |
| `EZGH_API_KEY` | An API key that takes precedence over the active profile's credential |
| `EZGH_PROFILE` | The profile to use |
| `EZGH_ORG` | The organization, by ID or slug |
| `EZGH_PROJECT` | The project, by ID, slug or name |
| `EZGH_DOMAIN` | The platform's domain |
| `EZGH_CREDENTIAL_STORE` | Where credentials are stored: `auto`, `keychain` or `file` |
| `EZGH_CONFIG_DIR` | The configuration directory |

Source: https://docs.ezghcloud.com/cli/profiles/index.mdx