Skip to main content
The CLI overview 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: One profile is active at a time. Every command runs as the active profile unless you override it. See Which profile the CLI uses for the full order.

Sign in and out

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

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

  • 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.
  • --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:
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 or workload identity 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

--grant is required and repeatable. The format is role:resourceType[:resourceName]:
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:
To skip handling the secret yourself, save it straight into a new profile:
--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:

Inspect and delete service users

The sign-in column shows whether the service user can sign in with a client secret, with workload identity, 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

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.
  • 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.
  • defaults, shared endpoint URLs used by profiles that don’t set their own.
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:
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. --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.
  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 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. 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.