Browse docs+

CLI

The R4 CLI is the easiest way for an agent to use R4 as its password manager.

Install

npm install -g @r4-sdk/cli

Requires Node.js 18 or newer.

Runtime Requirements

The CLI follows the same zero-trust runtime flow as the SDK:

an AGENT-scoped API key
a local PEM-encoded RSA private key
optional projectId and trustStorePath

Canonical Flow

Use this exact flow when you are setting up an agent with the CLI for the first time.

1. Install the CLI

npm install -g @r4-sdk/cli

2. Run the guided profile setup

r4 configure

That flow can either:

bootstrap a brand-new agent-only org and AGENT API key
or save an existing access key, secret, and private-key path

By default it stores the profile under:

~/.r4/
  config.json
  profiles/<profile>/credentials.json
  profiles/<profile>/private-key.pem
  profiles/<profile>/trust-store.json

3. Verify the resolved runtime identity

r4 space info

This confirms the active profile, API-key scope, principal, base URL, and the managed credential/private-key/trust-store paths.

4. Register and verify the zero-trust path

If you used the bootstrap mode in r4 configure, the first public key is already registered. If you saved existing credentials instead, run:

r4 doctor

This first public-key registration should happen before operators add the agent to security groups, projects, or direct vault shares.

5. List visible vaults

r4 vault list-vaults

6. List visible items

r4 vault items

7. Fetch one secret value

r4 vault get GITHUB_PRODUCTION_TOKEN

Shortcut

If you already have a credentials handoff file and want the older one-shot bootstrap, use:

r4 agent init --credentials-file ./agent-creds.csv

That reads the handoff file, generates the key if needed, registers the public key, saves the profile, and runs r4 doctor.

If you only need to save an existing key non-interactively, r4 auth login still works too.

Core Commands

List visible vaults

r4 vault list-vaults

List locally decrypted environment variables

r4 vault list

List vault items and env-style field names

r4 vault items

List vault item metadata without local decryption

r4 vault list-items
r4 vault items --metadata-only

Search vault items by name

r4 vault search github

Get one secret value

r4 vault get GITHUB_PRODUCTION_TOKEN

Run a command with secrets injected

r4 run -- node deploy.js
r4 run --prefix R4 -- docker compose up

Call any machine endpoint directly

r4 machine request GET /me
r4 machine request POST /webhook --body '{"name":"primary","url":"https://example.com/r4"}'

Show the current runtime identity and managed paths

r4 space info
r4 profile show
r4 auth whoami

JSON Output

All major CLI commands support --json:

r4 auth whoami --json
r4 vault items --json
r4 vault search github --json
r4 vault list --json

How the CLI Uses R4

On first use, the CLI:

resolves the selected named profile from ~/.r4/config.json
reads split credentials from ~/.r4/profiles/<profile>/credentials.json
authenticates with the AGENT API key
derives the matching public key from the local private key
registers that public key with R4 when needed
becomes eligible for vault-backed access grants after that first registration
retrieves the wrapped vault DEK and signer directory
verifies trust metadata and checkpoints
decrypts shared secrets locally

It also caches the last resolved identity with the saved profile so r4 space info can still tell you which scope and principal the profile was last verified as, even if the current live lookup is unavailable.

Managed Storage

The CLI now separates general profile settings from secret material:

~/.r4/
  config.json
  profiles/<profile>/credentials.json
  profiles/<profile>/private-key.pem
  profiles/<profile>/trust-store.json

config.json stores the current profile, runtime settings, and cached identity metadata
credentials.json stores split accessKey and secretKey
the default managed private key and trust store live beside those credentials

Troubleshooting

Use r4 doctor first. It registers the public key idempotently, checks visible vaults, checks wrapped keys, and verifies the local decrypt path.

Exact error	Fix
`No API key found. Provide one via:`	Set `--api-key`, `R4_API_KEY`, or both `R4_ACCESS_KEY` and `R4_SECRET_KEY`. Then save it with `r4 auth login`.
`No private key path found. Provide one via:`	Run `r4 configure` to create the managed key, or pass `--private-key-path` / `R4_PRIVATE_KEY_PATH` to point at an existing PEM file.
`R4 API Error [agent_scope_required]: This endpoint requires an AGENT-scoped API key.`	Use the agent API key from Platform -> Developer -> Agents. USER, TENANT, and ORG keys are not the agent retrieval path.
`R4 API Error [wrapped_key_not_found]: No wrapped key found for this agent and vault.`	Register the public key first, then ask the operator to re-share or re-assign the vault, project, or security-group access so wrapped keys are created for this agent.
`R4 SDK: failed to register the local agent public key.`	Confirm the API key is AGENT-scoped and the private key PEM matches the runtime identity you expect. Re-run `r4 doctor`.
`Failed to fetch public transparency witness artifact (403).`	Allow outbound access to `https://transparency-prod.r4.dev` for production or `https://transparency-dev.r4.dev` when targeting `https://dev.r4.dev`, or point the CLI at a custom witness URL for other environments.

If decryption is failing but access looks correct, use r4 vault list-vaults, r4 vault list-items, or r4 vault items --metadata-only to inspect metadata without relying on the local private-key decrypt path.

When to Use the CLI

Choose the CLI when the runtime:

runs shell commands
needs quick password lookup
wants an AWS-style named profile with inspectable managed local state
wants simple JSON output for scripting
wants r4 run style environment injection

Choose the Node SDK when the runtime already runs inside Node.js code.

Use r4 machine request when the raw machine API already exposes the workflow you need but the higher-level CLI commands have not wrapped it yet.

If the CLI is missing a capability you need and the current SDK, MCP server, or raw machine API also does not cover it, submit product-gap feedback through POST /api/v1/machine/feedback with an AGENT API key. Do not include secrets or private user data in that payload.