Skip to main content
The Ryvn CLI manages environments, services, installations, and releases from your terminal. It calls the same Ryvn API as the dashboard. This page gets you set up. For every command and flag, see the CLI reference.

Install

Recommended
This detects your OS and architecture, downloads the latest release, and adds ryvn to your PATH. Homebrew
Homebrew installations do not auto-update. Run brew upgrade ryvn periodically to get the latest features and security fixes.
Verify the installation:

Authenticate

Log in with your Ryvn account using the browser-based device flow:
For a self-hosted or BYOC Ryvn instance, pass its API URL:
The console URL works too; it redirects to the API discovery endpoint. When no scheme is provided, the CLI assumes https://. The CLI fetches the instance’s public discovery document and derives the issuer, Zitadel project, CLI device-flow client, console, and access proxy URLs from that one address. It writes a profile named after the instance host and makes that profile active. Use --profile as well when you want a different profile name. Profiles can include a tunnel-url field. This is the base URL used when ryvn connect writes a kubeconfig for environment access. Environments that require approval before granting cluster access are covered in Just-in-time kubectl access.

Upgrade

The CLI checks for updates automatically. To upgrade:
If you installed via Homebrew, use brew upgrade ryvn instead — ryvn upgrade is not supported for Homebrew installations.

Run your first commands

Commands follow a verb and a resource type. List your services, look at one installation, and stream its logs:
-e selects the environment. Run ryvn --help for the full command list, or ryvn <command> --help for any one command. The CLI reference covers each verb and the installation commands such as rollback, pin, and restart.

Using the CLI with agents

For CI, remote agents, or shared automation, use a service user instead of sharing personal credentials. Service users provide scoped, programmatic access that you can assign and revoke independently.

Create a service user

Service users provide scoped, programmatic access to your Ryvn organization. Create one from the CLI:
Choose the least-privileged role that gives the agent the access it needs. This outputs a client ID and client secret. Save these securely. The client secret cannot be retrieved again.

Use service users via profiles

For agents running on your local machine, create a profile with the service user credentials:
Then set it as the active profile:

Use service users via environment variables

For CI pipelines, remote servers, or agent runtimes, pass credentials via environment variables:
This lets the CLI authenticate non-interactively and select the correct organization. Pass -e or --environment to commands that target an environment.
In GitHub Actions jobs with permissions: id-token: write, the CLI authenticates as the repository’s CI identity and ignores RYVN_CLIENT_ID / RYVN_CLIENT_SECRET. To run a job as a service user instead, omit id-token: write. See Which identity a job uses.