Profiles

A profile is a named slot that holds one identity for the CLI: its credentials (either OAuth tokens or an API key) together with the organization that identity is currently working in. Profiles let you keep several logins side by side and switch between them without re-authenticating.

This is most useful when you work across separate organizations or identities. Imagine you are a consultant with a login at two client companies, Acme Corp and Globex. Keep one profile per company and switch with a single command, instead of logging out and back in each time:

gpilot profile use acme      # work as your Acme login…
gpilot profile use globex    # …then switch to Globex

Each profile remembers its own credentials and organization, so switching is instant and nothing carries over between them.

The layout is modeled on the AWS CLI: a config.toml that records the active profile and per-profile settings, plus one credentials file per profile. See where configuration is stored.

The default profile

If you never mention a profile, the CLI uses one called default. A plain gpilot auth login logs into default, and every other command reads from it.

Create or log into a named profile

--profile is a global option, accepted by every command. Log in while targeting a specific profile; it is created if it does not exist. Continuing the two-company example, set up one profile per client:

gpilot --profile acme auth login     # your login at Acme Corp
gpilot --profile globex auth login   # your login at Globex

Each profile carries its own credentials and its own selected organization, so acme and globex can point at different organizations and even different identities (one OAuth, one API key).

A successful login also makes that profile the active one, so after the two commands above globex is active. With --profile, auth login always logs in again, even when the profile still holds a valid login.

A newly created profile name may contain letters, digits, ., _ and -, up to 64 characters. Profiles created by older CLI versions keep working under whatever name they were given.

List profiles

gpilot profile list

One row per configured profile, with a * marking the active one, plus its organization, authentication method (oauth or api_key) and the email behind an OAuth login. It reads the profile store only and never calls the GraphPilot API.

With -o json it prints one array of { profile, active, kind, organization, email }, the field names profile show uses; -o jsonl prints one object per line and -o yaml one document. kind is oauth, api_key, or error when the stored credential cannot be read; organization and email are null when the profile holds none. An empty store is [].

Inspect one profile

gpilot profile show           # the active profile
gpilot profile show globex    # a specific one

The offline counterpart to auth status: it reports what is on disk (organization, selected service, email, remaining token lifetime, and an api_url override when one is set) without asking the GraphPilot API whether the credential is still accepted. That is the answer you want when the network is the thing that is failing.

With --format json (or yaml) it prints one document:

{
  "profile": "globex",
  "active": false,
  "kind": "oauth",
  "organization": "org_01J…",
  "service": "checkout-api",
  "email": "ada@example.com",
  "expires_in_secs": 240
}

kind is oauth or api_key. organization, service, email and expires_in_secs are null when the profile holds none (an API key has no email or expiry). api_url appears only when the profile overrides the API endpoint. A profile with no stored credential is an error, not an empty document.

Switch the active profile

gpilot profile use globex

This makes globex the default for subsequent commands by updating config.toml. Only a profile that holds a stored credential can be made active; for any other name the command exits 1 and names the gpilot --profile <name> auth login that creates it.

Per-command and environment overrides

You can also select a profile without changing the on-disk default:

Per command, with the global --profile flag:
Terminal window
```
gpilot --profile globex auth status
```
For a shell session, via the environment variable:
Terminal window
```
export GPILOT_PROFILE=globex
```

The CLI resolves which profile to use in this order: a --profile flag, then GPILOT_PROFILE, then the active_profile from config.toml. The one exception to “without changing the on-disk default” is auth login: a successful login makes the profile it logged into the active one.

Rename a profile

gpilot profile rename globex globex-eu

Renames the profile in place, credentials and configuration together, without logging in again. It is refused if the target name already exists.

Log out versus delete

The two are different, and the difference is what stays behind:

gpilot auth logout                 # clear the credential, keep the profile
gpilot profile delete globex       # remove the profile entirely

auth logout drops the stored credential for the active profile and leaves the profile standing, including its selected service, so logging back in resumes where you were. Use --profile (or GPILOT_PROFILE) to target a different one, or gpilot auth logout --all to clear every profile’s credential at once.

profile delete removes the credential and the config.toml entry. It takes several names at once, or --all for every configured profile, validates every name before deleting any of them, and asks for confirmation naming the organization and service about to be lost. In a non-interactive shell, where the prompt cannot be shown, it refuses unless you pass --yes. Deleting the active profile falls back to default.

Know which profile you are in

Commands that act on an organization or a service print a context line on stderr naming the profile, organization and service before their output, including in CI. See the context line.

Signing in: log in, check your status, and log out.
Where configuration is stored: the files behind each profile.
Command reference: every gpilot profile subcommand.