@r4-sdk/cli

Official R4 CLI for local R4 auth profiles. Use it to approve a terminal as an account device, configure an agent runtime with API credentials, and inspect the current auth state.

The CLI is a standalone public package with a small local command layer.

Requirements

• Node.js 18 or newer
• An R4 account created through the web UI

Installation

Install the CLI package:

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

Manual package installation:

npm install -g @r4-sdk/cli

Confirm the installed binary:

r4 --version

Update the CLI later from the CLI itself:

r4 update

First Run

Create your account in the R4 web UI first, then choose the profile type:

r4 configure

Approve the CLI as a trusted account device:

r4 login

The CLI opens the browser approval flow, generates a local device key, stores an encrypted local access token, and uses that login for device API access. Account registration is not available from the CLI.

Configure an agent after creating it in the web UI and downloading the runtime JSON config:

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

The downloaded config contains the agent ID, API credentials, and private key. The CLI verifies the API credentials, stores the private key under ~/.r4, and saves the agent profile for local SDK use.

Profile Storage

Managed profile state lives under ~/.r4/:

~/.r4/
  config.json
  update-check.json
  cache/
  profiles/
    <profile>/
      device-secrets.json
      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-secrets.json stores encrypted account device tokens and local device keys.
• credentials.json stores agent API credentials for agent profiles.
• private-key.pem stores the local agent runtime private key.

Keep ~/.r4/ out of source control and CI artifacts. Run r4 reset to delete this directory after a confirmation prompt and start with a clean local environment.

Global Options

| Flag | Description | | --- | --- | | --profile <name> | CLI profile name. Also supports R4_PROFILE. | | --dev | Use https://dev.r4.dev unless --base-url is set. | | --base-url <url> | API base URL. Defaults to https://r4.dev. | | --json | Print machine-readable JSON where supported. |

Common Workflows

Identity And Health

r4 auth status
r4 whoami
r4 auth whoami
r4 doctor

Load decrypted environment variables for a project from the selected agent profile without printing secret values:

r4 project env production-infrastructure

The command reports how many fields marked as environment variables were found. To make the values available to a child process, pass the command after --:

r4 project env production-infrastructure -- node server.js

Show project metadata by ID or slug:

r4 project get production-infrastructure

Use these commands first when debugging device login or local key approval issues.

Command Groups

| Group | Purpose | | --- | --- | | configure | Choose account login or configure an agent profile. | | auth | Login, logout, status, diagnostics, and identity checks. | | doctor | Device login and local key health checks. | | profiles | List and switch local profiles. | | project | Project lookup and project-scoped runtime helpers such as project env. | | reset | Delete local config, encrypted device secrets, and cache. | | update | Update the installed R4 CLI package to the latest version. |

Security Notes

• Registration and onboarding happen only in the R4 web UI.
• Device tokens and local device keys are encrypted before storage.
• Prefer named profiles over shell history for local workflow state.

Development

pnpm install
pnpm run typecheck
pnpm run test
pnpm run test:pack
pnpm run build

npm pack --dry-run is covered by pnpm run test:pack; it verifies that source files and tests are excluded from the published tarball.