CLI

The R4 CLI manages local R4 profiles for terminals and runtimes. A profile can authenticate as either:

• an account, approved through browser device login
• an agent, configured with AGENT API credentials and a local runtime private key

Use the web UI to create accounts and the Platform agent wizard to mint AGENT runtime credentials. The CLI stores and switches the local profiles that use those credentials.

Install

Install the CLI package:

curl -fsSL https://r4.dev/cli/install.sh | sh

Manual package installation:

npm install -g @r4-sdk/cli

Requires Node.js 18 or newer.

First Run

Create your account through the website first. Then choose the profile type:

r4 configure

For an account profile, start the browser approval flow and approve this terminal as a trusted device:

r4 login

The CLI opens the approval URL, shows a verification code, generates a local device key, and saves the encrypted token under ~/.r4/. Use r4 login --no-browser when the terminal cannot open a browser. Use r4 login --device-name "Build laptop" to control the device label shown in the approval screen.

The local secrets file is encrypted with your CLI unlock password. For non-interactive login setup, R4_CLI_PASSWORD can supply that password.

For an agent profile, create the agent in the web UI, download the one-time runtime JSON config, then run:

r4 configure agent --config ./openclaw-agent-runtime.json

The CLI imports the agent ID, API credentials, and private key from that file, verifies the credentials, stores the private key under the selected profile, and switches to that profile. The public key and selected security groups are registered during web UI agent creation, so normal CLI configuration does not need a separate public-key registration step.

Common Commands

Check the saved device session and account:

r4 auth status
r4 whoami
r4 auth whoami
r4 doctor
r4 auth diagnose

Print the decrypted environment-variable JSON for a project from the selected agent profile:

r4 project env PROJECT_ID

This command requires an agent profile imported with r4 configure agent --config <path>. It uses the profile's AGENT API key and local private key, filters vault discovery to the provided project ID, fetches only fields marked as environment variables from the machine API's narrow environment-field route when available, decrypts those values locally, and prints a JSON object such as:

{
  "PRIMARY_DATABASE_PASSWORD": "..."
}

Pass a trailing command to inject the decrypted variables into a child process instead of printing them. The CLI runs the command with the merged environment and passes its exit code through:

r4 project env PROJECT_ID -- node server.js

Inspect a project by ID or slug:

r4 project get PROJECT_ID

Manage local profiles and device sessions:

r4 profiles
r4 profiles use <profile>
r4 auth logout
r4 auth logout --all

Remove local CLI state:

r4 reset

Update the CLI to the latest published version:

r4 update

License Commands

Purchase, inspect, and tear down R4-managed licenses through the Pincer machine API without leaving the terminal.

Start a purchase and wait for it to finish:

r4 licenses purchase \
  --license-id LICENSE_SLUG \
  --vault-name "New Vault Name" \
  --wait

r4 licenses purchase mirrors the POST /licenses/purchase request fields as flags, including --domain-mode, --vault-id/--vault-name, --project-mode/--project-id/--project-name, --dry-run, and browser-activation options. With --wait it polls purchase status, auto-resumes recoverable failures (--auto-resume-attempts, default 8), and can complete the encrypted vault handoff with --complete-vault-handoff. Use --resume <purchaseId> to attach to an existing purchase. See Pincer: Purchase for the underlying flow.

Load the decrypted environment for a provisioned license, or run a command with it injected:

r4 licenses env LICENSE_INSTANCE_ID
r4 licenses env LICENSE_INSTANCE_ID -- node server.js

Like r4 project env, this requires an agent profile: it calls GET /licenses/:licenseInstanceId/environment, unwraps the vault keys with the local private key, and decrypts the license credentials locally.

Show distributor charges (for example AWS usage billed through Pax8) for R4-managed licenses:

r4 licenses charges --month 2026-06
r4 licenses charges --license-instance-id LICENSE_INSTANCE_ID --lines

Terminate and archive a license:

r4 licenses archive LICENSE_INSTANCE_ID --wait

Termination polls GET /licenses/terminations/:terminationId/status until provider teardown succeeds; --resume <terminationId> re-attaches to a failed run. See Pincer: Terminate.

Read and diagnostic commands support --json where useful, including auth status, whoami, auth whoami, doctor, auth diagnose, and profiles. r4 reset --json requires --yes so scripts cannot delete local state by accident.

Global Options

Explicit --base-url wins over --dev. A successful login persists the chosen runtime mode on that profile.

Managed Storage

The CLI stores local profile and device-login state under:

~/.r4/
  config.json
  update-check.json
  cache/
  profiles/
    <account-profile>/
      device-secrets.json
    <agent-profile>/
      credentials.json
      private-key.pem
      trust-store.json

config.json stores non-secret profile settings. update-check.json and cache/ store local cache data. Device tokens and local device keys are encrypted before they are written to each account profile's device-secrets.json. Agent profiles store API credentials in credentials.json and keep the runtime private key in private-key.pem; both files are written with owner-only permissions. Agent profiles also keep a trust-store.json that pins trusted signer keys by concrete user key-pair or agent encryption-key ID.

Keep ~/.r4/ out of source control and CI artifacts.

Troubleshooting

Use r4 doctor or r4 auth diagnose first. They check the selected profile, device token, account lookup, organization memberships, cached private keys, and local key approval state.

When to Use the CLI

Choose the CLI when you want browser-approved terminal login, agent profile bootstrap, simple JSON output for auth state, a quick local auth health check, project/license environment injection into shell commands, or terminal-driven license purchase and teardown. Use the web UI for account registration and agent credential creation. Use the Node SDK or MCP server for in-process AGENT runtime secret retrieval.