Profiles and configuration

A profile is one way of using EZGH Cloud: its own credential 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

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

    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.

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.

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.

• 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.
• 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:

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:

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:

default_profile = "work"

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

[profiles.ci]
output = "json"

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:

The same directory holds credentials.json when credentials can’t go in the system keychain. See Where credentials are stored.

Environment variables