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

# Use the Ryvn CLI

> Install the Ryvn CLI, sign in, run your first commands, and set it up for CI and agents

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](https://ryvn.ai/docs/cli.md).

## Install

**Recommended**

```bash theme={null}
curl -fsSL https://ryvn.ai/install.sh | bash
```

This detects your OS and architecture, downloads the latest release, and adds `ryvn` to your `PATH`.

**Homebrew**

```bash theme={null}
brew tap ryvn-technologies/tap
brew install ryvn
```

> [!WARNING]
>
> Homebrew installations do not auto-update. Run `brew upgrade ryvn` periodically to get the latest features and security fixes.

Verify the installation:

```bash theme={null}
ryvn --version
```

## Authenticate

Log in with your Ryvn account using the browser-based device flow:

```bash theme={null}
ryvn auth login
```

For a self-hosted or BYOC Ryvn instance, pass its API URL:

```bash theme={null}
ryvn auth login --instance https://api.vendor.example
```

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](https://ryvn.ai/docs/guides/jit-kubectl-access.md).

## Upgrade

The CLI checks for updates automatically. To upgrade:

```bash theme={null}
ryvn 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:

```bash theme={null}
ryvn get service
ryvn describe installation my-app -e production
ryvn logs installations my-app -e production
```

`-e` selects the environment. Run `ryvn --help` for the full command list, or `ryvn <command> --help` for any one
command. The [CLI reference](https://ryvn.ai/docs/cli.md#core-commands) 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:

```bash theme={null}
ryvn auth create service-user my-agent --grant viewer:org
```

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.

```
Service user "my-agent" created successfully

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

Save these credentials 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:

```bash theme={null}
ryvn auth create profile my-agent \
  --client-id your-client-id \
  --client-secret your-client-secret \
  --org-id your-org-id
```

Then set it as the active profile:

```bash theme={null}
ryvn auth use profile my-agent
ryvn get service
```

### Use service users via environment variables

For CI pipelines, remote servers, or agent runtimes, pass credentials via environment variables:

```bash theme={null}
export RYVN_CLIENT_ID=your-client-id
export RYVN_CLIENT_SECRET=your-client-secret
export RYVN_ORG_ID=your-org-id
```

This lets the CLI authenticate non-interactively and select the correct organization. Pass `-e` or `--environment` to commands that target an environment.

> [!NOTE]
>
> 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](https://ryvn.ai/docs/deploy/github-actions-integration.md#which-identity-a-job-uses).
