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-idand--client-secret. You can also set it explicitly with--type useror--type service-user. Passing client credentials with--type userfails withuser profile cannot have client credentials. --org-idsets 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.
ryvn auth create -f profile.yaml, using kind: 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]:
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:
--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
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 orgaccepts a slug, name, or ID, and saves the organization’s ID to the active profile. It fails withorganization "<name>" not foundif you don’t belong to it.--organdRYVN_ORG_IDchange 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 theryvn 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.
.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:- The
--profileflag. - The
RYVN_PROFILEenvironment variable. - The
profilekey in the nearest.ryvn/settings.yaml. current-profilein~/.ryvn/credentials.yaml, whichryvn auth use profilesets.- A profile named
default.
profile "<name>" not found.
Which organization the CLI uses
The first match wins:- The
--orgflag. - The
RYVN_ORG_IDenvironment variable. org-idin the nearest.ryvn/settings.yaml.- The organization saved on the profile, which
ryvn auth use orgsets. - 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: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.- Workload identity, when the job provides an OIDC token. GitHub Actions jobs with
id-token: write, and jobs that setRYVN_OIDC_SOURCE,RYVN_OIDC_TOKEN,RYVN_OIDC_TOKEN_FILE, orRYVN_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. - Client credentials, from
--client-idand--client-secret, theRYVN_CLIENT_*variables, or a service-user profile, in that order. - The stored login of the active
userprofile. The CLI refreshes the access token automatically when it expires.
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
Runryvn auth status and compare it with the orders in How the CLI decides. The usual causes are:
- A
.ryvn/settings.yamlin the current directory tree names a differentprofileororg-id. RYVN_PROFILE,RYVN_ORG_ID,RYVN_CLIENT_IDandRYVN_CLIENT_SECRET, orRYVN_ACCESS_TOKENis 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 withtoken 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.