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

# Profiles and credentials

> Sign in to the Ryvn CLI, manage profiles, service users, and organizations, and understand which credential a command uses

The [CLI overview](https://ryvn.ai/docs/cli.md) covers installing the CLI and signing in once. This page covers everything after that: keeping several identities side by side, creating service users for automation, switching organizations, and finding out why a command runs as the wrong identity.

## Profiles

A profile is a named identity plus the settings that go with it: the credentials, the organization, and the instance the CLI talks to. You can keep several profiles, such as your own login, a CI service user, and a login on a self-hosted instance, and switch between them without signing in again.

There are two types:

| Type | Authenticates with | Created by |
| - | - | - |
| `user` | Your browser login | `ryvn auth login` or `ryvn auth create profile <name>` |
| `service-user` | A client ID and client secret | `ryvn auth create profile <name> --client-id ... --client-secret ...`, or `ryvn auth create service-user --save-profile` |

One profile is active at a time. Every command runs as the active profile unless you override it. See [Which profile the CLI uses](#which-profile-the-cli-uses) for the full order.

## Sign in and out

```bash theme={null}
ryvn auth login                      # active profile
ryvn auth login --profile staging    # a specific profile
ryvn auth status                     # profile, auth type, token expiry, organization
ryvn auth logout                     # remove the active profile's stored login
```

`ryvn auth login` prints a code and a URL, then tries to open your browser. If it can't, open the URL on any device and enter the code. The command waits until you approve, so an agent running it should show you the URL and code and wait rather than retry.

On a fresh install, `ryvn auth login` creates a profile named `default`. With `--profile <name>`, it creates that profile as a `user` profile if it doesn't exist, and leaves the active profile unchanged unless none is set. For a self-hosted or BYOC instance, see `--instance` in the [CLI overview](https://ryvn.ai/docs/cli.md#authenticate).

`ryvn auth logout` removes the stored login from the profile. The profile, its organization, and its URLs stay, so the next `ryvn auth login` picks up where it left off.

> [!NOTE]
>
> `ryvn auth login` and `ryvn auth logout` work only on `user` profiles. On a `service-user` profile they fail with `cannot login to profile "ci-bot": it is a service-user profile` (or `cannot logout from ...`). To change a service-user profile, delete it and create it again.

### Where tokens are stored

`ryvn auth login` stores your tokens in the operating system's credential store: Keychain on macOS, Secret Service on Linux, and Credential Manager on Windows. There is one entry per profile, under the service name `ryvn-cli`. Only non-secret settings go in `~/.ryvn/credentials.yaml`.

If no credential store is available, such as on a headless Linux host without a keyring, the CLI saves the tokens in `~/.ryvn/credentials.yaml` in plain text and prints a warning. To always use the file, pass `--insecure-storage`:

```bash theme={null}
ryvn auth login --insecure-storage
```

`ryvn auth status` shows where the active profile's tokens live (`keyring` or `file`). Deleting a profile or logging out also removes its credential store entry.

## Manage profiles

```bash theme={null}
ryvn auth get profile              # list profiles; the active one is marked with *
ryvn auth use profile staging      # make staging the active profile
ryvn auth describe profile staging # type, organization, client ID, token expiry
ryvn auth delete profile staging   # remove a profile
```

`get` and `describe` accept `-o json`. `describe` never prints tokens or client secrets. `delete` refuses to remove the active profile: switch to another one first with `ryvn auth use profile`.

### Create a profile

```bash theme={null}
# A user profile: starts the browser login right away
ryvn auth create profile work

# A service-user profile: saved without a login
ryvn auth create profile ci-bot \
  --client-id "$CLIENT_ID" \
  --client-secret "$CLIENT_SECRET" \
  --org-id 00000000-0000-0000-0000-000000000000

# A new profile that reuses another profile's endpoints and organization
ryvn auth create profile staging --from work
```

* **User profiles** (the default) start the browser login immediately. The profile is saved, and made active, only if the login succeeds. If it fails, nothing is written.
* **Service-user profiles** are saved without a login. The CLI infers the type when you pass both `--client-id` and `--client-secret`. You can also set it explicitly with `--type user` or `--type service-user`. Passing client credentials with `--type user` fails with `user profile cannot have client credentials`.
* **`--org-id`** sets the profile's organization. See [Organizations](#organizations).
* **`--from <profile>`** copies the source profile's API, auth, and console URLs and its organization. It never copies credentials, and explicit flags win over copied values.
* A name that already exists fails with `profile "<name>" already exists`.

You can also create a profile from a file with `ryvn auth create -f profile.yaml`, using `kind: Profile`:

```yaml theme={null}
kind: Profile
metadata:
  name: ci-bot
spec:
  type: service-user
  clientId: "my-client-id"
  clientSecret: "my-client-secret"
  orgId: "00000000-0000-0000-0000-000000000000"
```

> [!WARNING]
>
> A service-user profile stores its client secret in `~/.ryvn/credentials.yaml` in plain text. The file is readable only by your user, but on a shared or ephemeral machine, prefer [environment variables](#environment-variables) or [workload identity](https://ryvn.ai/docs/cli/workload-identity.md) over saving a profile.

## Service users

A service user is a non-interactive identity for CI, scripts, and agents. You grant it roles on the organization or on environments, and it authenticates with a client ID and client secret.

### Create a service user

```bash theme={null}
ryvn auth create service-user ci-bot --grant developer:environment:staging
```

`--grant` is required and repeatable. The format is `role:resourceType[:resourceName]`:

| Part | Values |
| - | - |
| `role` | `admin`, `billing_admin`, `developer`, `operator`, `viewer`. See [Roles](https://ryvn.ai/docs/iac/access-policy.md#roles). |
| `resourceType` | `org`, `environment` |
| `resourceName` | An environment name. Leave it out to cover every resource of that type. |

```bash theme={null}
# Read-only on the whole organization, plus developer on one environment
ryvn auth create service-user ci-bot \
  --grant viewer:org \
  --grant developer:environment:staging
```

Grant the least privilege the job needs. An unknown role fails with `invalid role`, and an environment that doesn't exist fails with `environment "<name>" not found`.

The command prints a client ID and a client secret:

```
Service user "ci-bot" created successfully

Client ID:     abc123...
Client Secret: secret456...

Save these credentials securely. The client secret cannot be retrieved again.
```

To skip handling the secret yourself, save it straight into a new profile:

```bash theme={null}
ryvn auth create service-user ci-bot --grant admin:org --save-profile ci-bot
```

`--save-profile` fails before creating anything if the profile name is taken. If creating the service user succeeds but saving the profile fails, the CLI prints the credentials so they aren't lost. Add `-o json` to get the credentials as JSON.

You can also create one from a file with `ryvn auth create -f service-user.yaml`:

```yaml theme={null}
kind: ServiceUser
metadata:
  name: ci-bot
spec:
  grants:
    - role: viewer
      resourceType: org
    - role: developer
      resourceType: environment
      resourceName: staging
```

### Inspect and delete service users

```bash theme={null}
ryvn auth get service-user               # list service users in the current organization
ryvn auth describe service-user ci-bot   # roles, client ID, and sign-in methods
ryvn auth delete service-user ci-bot
```

The sign-in column shows whether the service user can sign in with a client secret, with [workload identity](https://ryvn.ai/docs/cli/workload-identity.md), or both. Deleting a service user removes its roles and the service user itself. The underlying identity isn't destroyed, so you can create a service user with the same name later.

### Replace a service user's grants

```bash theme={null}
ryvn auth replace -f service-user.yaml
```

`replace` takes the same `ServiceUser` file as `create`, and **removes every existing grant, then applies exactly the grants in the file**. A grant you leave out of the file is removed. It fails with `service user "<name>" not found` if the name doesn't match an existing service user. It changes grants only: the service user's client ID and secret stay the same.

## Organizations

The organization is the top-level scope for everything you read or change. If you belong to more than one, check which one a command targets before you change anything.

```bash theme={null}
ryvn auth get org                  # organizations you can access; the active one is marked with *
ryvn auth use org my-org           # set the organization on the active profile
ryvn get environment --org my-org  # use another organization for one command only
```

* `ryvn auth use org` accepts a slug, name, or ID, and saves the organization's ID to the **active profile**. It fails with `organization "<name>" not found` if you don't belong to it.
* `--org` and `RYVN_ORG_ID` change the organization for a single command or shell without touching the profile. They accept a slug, name, or ID.
* If nothing sets an organization, the CLI uses the first organization your identity can access. If you belong to several, set one explicitly.

## Configuration files

You rarely need to edit these files. Use the `ryvn auth` commands instead.

### `~/.ryvn/credentials.yaml`

The CLI's own state, readable only by your user. It holds:

* `current-profile`, the active profile's name.
* `profiles`, with each profile's type, organization, and URLs. Service-user profiles also hold the client ID and secret. User profiles hold token metadata, and the tokens themselves only when they aren't in the [credential store](#where-tokens-are-stored).
* `defaults`, shared endpoint URLs used by profiles that don't set their own.

> [!WARNING]
>
> Never delete `credentials.yaml` to fix a problem with one profile. It holds every profile and every service-user secret, and deleting it leaves the matching credential store entries orphaned. Delete and re-create only the broken profile with `ryvn auth delete profile` and `ryvn auth create profile`.

### `.ryvn/settings.yaml`

A per-directory override that you can commit alongside a repository. The CLI looks for `.ryvn/settings.yaml` in the current directory, then in each parent directory, and uses the first one it finds. It holds settings only, never credentials:

```yaml theme={null}
profile: ci-bot
org-id: 00000000-0000-0000-0000-000000000000
```

| Key | Effect |
| - | - |
| `profile` | The profile to use in this directory tree |
| `org-id` | The organization to use |
| `api-url`, `auth-url` | Override the profile's endpoints |
| `project-id`, `tunnel-url` | Override the profile's identity project and access proxy URL, mainly for self-hosted instances |

> [!NOTE]
>
> A `profile:` in `.ryvn/settings.yaml` beats the active profile, so `ryvn auth use profile` appears to succeed but has no effect inside that directory tree. Run `ryvn auth status` to see which profile is in use, or pass `--profile` for one command.

### Legacy `~/.ryvn/config.yaml`

Older versions of the CLI kept their settings in `~/.ryvn/config.yaml`. The first time a newer CLI runs, it moves them into a profile named `default` in the new `credentials.yaml` format and makes it active. It saves the old files as `config.yaml.bak` and, if one existed, `credentials.yaml.bak`, then removes `config.yaml`.

If the legacy files hold both client credentials and a user login, the migration can't pick one and doesn't run. The CLI doesn't print that error by default; run any command with `--debug` to see it, then remove one set of credentials from the legacy files and run the command again.

## Environment variables

Environment variables override what's stored in profiles, which makes them the right tool for CI and one-off overrides. Flags such as `--org` override variables in turn.

| Variable | Meaning |
| - | - |
| `RYVN_ACCESS_TOKEN` | A bearer token you already have. Used as-is, ahead of every other credential, while it has more than a minute left. |
| `RYVN_CLIENT_ID`, `RYVN_CLIENT_SECRET` | A service user's client credentials. Both must be set; one alone is ignored. |
| `RYVN_ORG_ID` | The organization for this process. Accepts a slug, name, or ID. In [workload identity](https://ryvn.ai/docs/cli/workload-identity.md) jobs it must be an ID. |
| `RYVN_PROFILE` | The profile to use. Overridden by `--profile`. |
| `RYVN_API_URL` | The API URL, overriding the profile's. Defaults to `https://api.ryvn.app`. |
| `RYVN_AUTH_URL`, `RYVN_CONSOLE_URL`, `RYVN_PROJECT_ID`, `RYVN_DEVICE_CLIENT_ID` | Identity settings for a self-hosted instance. `ryvn auth login --instance` fills these in for you. |
| `RYVN_ACCESS_PROXY_URL` | The access proxy URL `ryvn connect` uses. The profile's `tunnel-url` sets the same value. |
| `RYVN_ACCESS_PROXY_INSECURE` | Skips TLS verification for the access proxy connection. Use only against a test instance. |
| `RYVN_ENVIRONMENT` | The default for `-e` on `ryvn run provisioner` only. No other command reads it, so pass `-e` explicitly. |
| `RYVN_OIDC_SOURCE`, `RYVN_OIDC_TOKEN`, `RYVN_OIDC_TOKEN_FILE`, `RYVN_OIDC_TOKEN_ENV`, `RYVN_SERVICE_USER`, `RYVN_BINDING_ID` | Select and configure [workload identity](https://ryvn.ai/docs/cli/workload-identity.md). |

`--client-id` and `--client-secret` also exist as flags (see `ryvn options`), but a secret on the command line is visible to other processes on the machine. Prefer the variables.

## How the CLI decides

### Which profile the CLI uses

The first match wins:

1. The `--profile` flag.
2. The `RYVN_PROFILE` environment variable.
3. The `profile` key in the nearest `.ryvn/settings.yaml`.
4. `current-profile` in `~/.ryvn/credentials.yaml`, which `ryvn auth use profile` sets.
5. A profile named `default`.

If the chosen profile doesn't exist, the command fails with `profile "<name>" not found`.

### Which organization the CLI uses

The first match wins:

1. The `--org` flag.
2. The `RYVN_ORG_ID` environment variable.
3. `org-id` in the nearest `.ryvn/settings.yaml`.
4. The organization saved on the profile, which `ryvn auth use org` sets.
5. The first organization your identity can access.

### Which credential the CLI uses

Once the profile is chosen, the CLI takes the first credential it finds:

1. **`RYVN_ACCESS_TOKEN`**, while it is valid. If it has expired, the CLI moves on only to client credentials or a workload identity source. It doesn't fall back to a stored login, so unset the variable to use your own login again.
2. **Workload identity**, when the job provides an OIDC token. GitHub Actions jobs with `id-token: write`, and jobs that set `RYVN_OIDC_SOURCE`, `RYVN_OIDC_TOKEN`, `RYVN_OIDC_TOKEN_FILE`, or `RYVN_OIDC_TOKEN_ENV`, use it ahead of client credentials. Platform sources detected on their own, such as the Kubernetes service account token, step aside when client credentials or a stored login exist. See [Workload identity](https://ryvn.ai/docs/cli/workload-identity.md).
3. **Client credentials**, from `--client-id` and `--client-secret`, the `RYVN_CLIENT_*` variables, or a service-user profile, in that order.
4. **The stored login** of the active `user` profile. The CLI refreshes the access token automatically when it expires.

This order is by credential, not by profile. If `RYVN_CLIENT_ID` and `RYVN_CLIENT_SECRET` are set while a `user` profile is active, commands run as the service user. If `RYVN_ACCESS_TOKEN` is set, it wins over a `service-user` profile.

`ryvn auth status` reports the result: the profile, the auth type (`user`, `service-user`, `access-token`, or a workload identity type), the token expiry, and the organization. `auth status` matches the organization by ID only. If `--org` or `RYVN_ORG_ID` holds a slug or name, it can show your first organization even though commands target the one you named, so check with `ryvn auth get org` instead.

## Troubleshooting

### `failed to get token: no user credentials found`

The active profile has no stored login and nothing else supplies a credential. Run `ryvn auth status` to see which profile is active, then `ryvn auth login`. For a service user, check that both `RYVN_CLIENT_ID` and `RYVN_CLIENT_SECRET` are set.

### `user credentials are stored in the OS credential store but could not be read from it`

The profile's tokens are in the credential store, and the CLI can't reach it. This is common on headless Linux hosts, in containers, and in SSH sessions where the keyring is locked or missing. Run `ryvn auth login` again. If the host has no credential store, use `ryvn auth login --insecure-storage`, or use a service user or [workload identity](https://ryvn.ai/docs/cli/workload-identity.md) instead.

### A command runs in the wrong organization or as the wrong identity

Run `ryvn auth status` and compare it with the orders in [How the CLI decides](#how-the-cli-decides). The usual causes are:

* A `.ryvn/settings.yaml` in the current directory tree names a different `profile` or `org-id`.
* `RYVN_PROFILE`, `RYVN_ORG_ID`, `RYVN_CLIENT_ID` and `RYVN_CLIENT_SECRET`, or `RYVN_ACCESS_TOKEN` is set in the shell and overrides the profile.
* The profile has no organization saved, so the CLI used the first one your identity can access. Fix it with `ryvn auth use org`.

`ryvn auth describe profile <name>` confirms the type and organization saved on a profile.

### Token expired

User access tokens refresh on their own using the stored refresh token. If that fails with `token expired and no refresh token available` or `failed to refresh token`, run `ryvn auth login` again. Service-user tokens are requested on demand, so an authentication failure for a service user usually means the client ID or secret is wrong, or the service user was deleted. An expired `RYVN_ACCESS_TOKEN` fails with `RYVN_ACCESS_TOKEN expired at <time> and no other credential source is configured`. Get a new token.

### `profile "<name>" not found`

`--profile`, `RYVN_PROFILE`, or a `.ryvn/settings.yaml` names a profile that doesn't exist. Run `ryvn auth get profile` to list the profiles you have.

### `ryvn upgrade` says the installation is managed by Homebrew

Run `brew upgrade ryvn` instead. `ryvn upgrade` doesn't update Homebrew installs. See [Upgrade](https://ryvn.ai/docs/cli.md#upgrade).
