Install
Recommendedryvn to your PATH.
Homebrew
Authenticate
Log in with your Ryvn account using the browser-based device flow: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:brew upgrade ryvn instead — ryvn upgrade is not supported for Homebrew installations.
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:Use service users via profiles
For agents running on your local machine, create a profile with the service user credentials:Use service users via environment variables
For CI pipelines, remote servers, or agent runtimes, pass credentials via environment variables:-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.Core commands
The CLI is organized around verbs. Each verb operates on one or more resource types.
Task-creating
ryvn command operations watch until completion by default. Use
--no-watch to return with a valid ryvn get installation-task monitoring command;
because it skips task discovery, it does not print the task UUID. ryvn command pin
and ryvn command unpin create no task and return immediately. The sync-backed
create, update, and delete verbs return their resource result without watching and
do not take the command task-control flags.
Run ryvn --help for the full command list, or ryvn <command> --help for details on any command.
Holding a release
ryvn command pin and ryvn set version-pin hold the installation’s current
release against release-channel updates without starting a deployment. If no
running release has been reported, they hold the target release. Neither pin
form accepts --version.
ryvn command enforce-deploy --version X pins X and starts an asynchronous
deployment task. The hold persists after deployment.
unpin removes a hold created by pin or enforce-deploy and allows release-channel
reconciliation. It does not roll back a deployment.
Git sync resource overview
ryvn get sync-resource (alias sync-resources) lists Git-sync resources.
Filter by resource kind, sync status (synced, drifted, unmanaged), or UUID.
Each flag can be repeated or comma-separated. Values within a flag are alternatives;
the three filters intersect.
gitSyncActive, counts, and resources.
The table distinguishes inactive Git sync from an active configuration with no
matching resources. Permission errors are reported by this command.
Git sync selectors
ryvn sync import --resolve-drift names resources with a
selector. Environment-scoped kinds (service installations, blueprint
installations) require an environment, either as an @<environment> suffix or
with -e/--environment — both forms are accepted everywhere, but naming the
environment twice is rejected, even when the values match. Org-scoped kinds
(services, environments, blueprints, and the rest) reject an environment
either way.
--resolve-drift also accepts the literal all and an inline JSON array. Each
element carries its own kind and name, plus environment for
environment-scoped kinds. Org-scoped kinds omit environment:
-e applies to a single selector only. Combining it with a JSON
array or with all is rejected; use the array elements’ own fields instead.Listing installations
ryvn get installation lists the installations you manage directly: standalone installations and children of your own or shared blueprints. Installations managed by the environment’s platform blueprint or by a marketplace blueprint are omitted by default; pass --all to include them.
Marketplace blueprints
The CLI supports browsing and installing marketplace blueprints. Marketplace blueprints use theryvn.app/ prefix:
Resource shares
Share a private blueprint with named consumer organizations, or, from the hub organization, with every organization on the hub. Each audience names the release channel consumers install from and the permissions it grants (blueprint.read, blueprint.install, blueprint.discover by default) and who controls upgrades (managed or consumerApproved). Consumers see offered shares with --incoming and accept or decline them; installations of a shared blueprint follow the audience’s channel and show it as coming from the share.