# Install the rzv CLI Install the rzv command-line tool, sign in, and choose a workspace. ## 1. Install on macOS or Linux The installer ships rzv 0.21.0 (release-2026-10-31-193326). It downloads the executable for your machine, verifies its SHA-256 checksum and installs it in ~/.local/bin. No separate Node.js installation or runtime is needed. Run this in a macOS or Linux terminal. If rzv is already installed, the same command updates it. Terminal · macOS and Linux ``` curl -fsSL https://runzivo.dev/downloads/rzv/install.sh | sh rzv version ``` Installing on Windows? Start here [See rzv releases, checksums and release notes](https://github.com/Runzivo/rzv-cli/releases) ## 2. Sign in Sign in with the GitHub identity you use for the customer portal. The CLI opens your browser at id.runzivo.dev, then stores a short-lived access token locally. It never prints a password or token to the terminal. Run whoami after sign-in to check your identity, profile and selected workspace. After upgrading from a version earlier than 0.19.0, sign in again to use the current identity provider. Terminal · sign in and check your identity ``` rzv login rzv whoami ``` ## 3. Select a workspace List the workspaces you belong to, then replace \ with an ID or slug from that list. Selection is saved for later workspace-scoped commands. Check whoami again to confirm the selection. Pass --workspace \, or -w, to use a different workspace for one command. RZV_WORKSPACE sets the default workspace for a shell. The older --account \ option is also accepted. Terminal · replace \ before running ``` rzv workspaces list rzv workspaces select rzv whoami ``` [Workspace command reference](https://runzivo.dev/docs/cli-commands/#workspaces-and-access) ## 4. Run your first read-only command List jobs in the selected workspace. Add --json when a script needs machine-readable output. This lists existing jobs; it does not start a workflow. Terminal · list jobs and inspect command help ``` rzv jobs list rzv jobs list --json rzv help jobs ``` [Read the rzv command reference](https://runzivo.dev/docs/cli-commands/) [Create your first sandbox](https://runzivo.dev/docs/sandboxes-quickstart/) ## Windows installation On Windows x86-64, download rzv-win32-x64.exe and SHA256SUMS from the same release. Open PowerShell in the download directory and calculate the executable's SHA-256 hash. Compare it with the matching entry in SHA256SUMS before running the file. After verification, rename the executable to rzv.exe and put it in a directory on PATH. Return to step 2 to sign in, then select a workspace. The shell installer above is for macOS and Linux, not Windows. PowerShell · verify the Windows download ``` Get-FileHash .\rzv-win32-x64.exe -Algorithm SHA256 ``` [Download the Windows executable and checksums](https://github.com/Runzivo/rzv-cli/releases) ## If rzv is not found The installer reports its install directory. If your shell cannot find rzv, add that directory to PATH. This example uses the default ~/.local/bin and applies to the current macOS or Linux shell. Add the same line to your shell's startup file to keep it for new terminals. Set RZV_INSTALL_DIR when running the installer to use a different directory. Terminal · macOS and Linux ``` export PATH="$HOME/.local/bin:$PATH" rzv version ``` ## Install a specific release Use the release tag when you need a fixed CLI version. This installs the version documented on this page. Terminal · macOS and Linux ``` curl -fsSL https://runzivo.dev/downloads/rzv/install.sh | sh -s -- --version=release-2026-10-31-193326 ``` ## Supported CLI platforms Builds are available for macOS on Apple Silicon and Intel, Linux on x86-64 and arm64, and Windows on x86-64. Each is a self-contained executable. Release files are rzv-darwin-arm64, rzv-darwin-x64, rzv-linux-arm64, rzv-linux-x64, and rzv-win32-x64.exe. CLI platforms do not change runner availability. Runzivo jobs run on Linux x64; macOS and Windows runners are not available instantly; they are provisioned on request (contact run@runzivo.dev). ## Use a separate sign-in profile Each profile keeps its own sign-in and selected workspace. This example creates a profile named work, lists profiles and makes work active. Use -p \ on any command for a one-off choice, or set RZV_PROFILE for a shell. Removing a profile removes its local sign-in. Terminal · optional profiles ``` rzv login -p work rzv profiles list rzv profiles use work rzv whoami -p work ``` ## Sign in without opening the browser automatically Use --no-browser to print the sign-in URL, then open it yourself. Run the CLI on the same machine as the browser, because the sign-in returns to a local callback listener. Terminal · manual browser opening ``` rzv login --no-browser ``` ## Sign out This removes the stored sign-in for the profile in use. Terminal · remove the current sign-in ``` rzv logout ``` ## Troubleshooting the CLI - “Credentials were rejected or expired”: sign in again with the command below. - “The requested workspace is not authorized for this account.”: list your workspaces and select one you can access. Contact support if you expect access. - “The customer API is unavailable”: wait and retry; contact support if it persists. - GitHub authorization denied or expired device code: GitHub's device flow was declined or timed out. Start authorization again. - GitHub installation authority denied: you must be an organization admin or owner. For an invalid or expired link state, start a fresh connection. Terminal · check sign-in, access and GitHub options ``` rzv login rzv workspaces list rzv help github ``` [See general troubleshooting and the support contact](https://runzivo.dev/docs/troubleshooting/) [GitHub connection commands](https://runzivo.dev/docs/cli-commands/#github) On this page and page tools