@r4-sdk/cli

Official R4 CLI -- manage vaults, projects, machine routes, and secrets from the terminal using the zero-trust Node SDK path.

Installation

npm install -g @r4-sdk/cli

Requires Node.js >= 18.0.0.

Commands

r4 configure

Guided setup for a named CLI profile.

• create a brand-new agent runtime through POST /api/v1/auth/auth/register-agent, including the required bootstrap billing top-off
• or manually save an existing access key, secret, and private key

r4 agent

Manage machine agents and bootstrap the local runtime.

• r4 agent list -- List visible agents
• r4 agent get <id> -- Show agent details including budget and security-group state
• r4 agent create -- Create an agent, optionally with inline permissions and a per-agent budget
• r4 agent update <id> -- Update agent name, budget, and security-group memberships
• r4 agent get-tenant-roles <id> -- Show the explicit and inherited tenant roles for an agent
• r4 agent set-tenant-roles <id> -- Replace the explicit tenant roles for an agent
• r4 agent init -- Read credentials, generate/reuse a private key, register the public key, send the local hostname claim for operator visibility, save the profile, and run a health check

r4 auth

Manage API key authentication.

• r4 auth login -- Save API key credentials to a named profile
• r4 auth logout -- Remove saved credentials
• r4 auth register-agent -- Public self-registration path that creates a fresh agent-only org/runtime, requires --stripe-payment-method-id pm_..., charges at least $20 of initial credit, and saves the result into the selected profile
• r4 auth status -- Show current authentication state
• r4 auth whoami -- Show the current profile identity, remote machine scope/context, and policy summary via GET /api/v1/machine/me
• r4 auth diagnose -- Alias for r4 doctor

r4 budget

Inspect and manage budgets.

• r4 budget list -- List visible budgets and their active windows
• r4 budget create -- Create a budget from inline JSON or --body-file

r4 billing

Inspect billing readiness.

• r4 billing readiness -- Show whether the org has a verified domain and positive credit balance

r4 doctor

Verify API key auth, remote machine identity, public-key registration, visible vaults, wrapped keys, and zero-trust health.

r4 domain

Manage external domains.

• r4 domain list -- List visible external domains
• r4 domain add <domain> -- Register a new external domain and print TXT verification instructions
• r4 domain verify <id> -- Trigger TXT verification for a domain

r4 machine

Call the headless machine API directly.

• r4 machine request <method> <path> [--body <json> | --body-file <path>] -- Send an authenticated request to any machine API route

r4 monitoring

Inspect scoped machine monitoring summaries.

• r4 monitoring entity-counts -- Show the visible tenant/user/security-group/vault/domain/agent/project counts

r4 profile

Manage saved CLI profiles.

• r4 profile list -- List saved profiles
• r4 profile show -- Show the active profile, identity, and managed storage paths
• r4 profile use <name> -- Switch the active profile

r4 space

Inspect the active runtime context.

• r4 space info -- Show who the current profile is authenticated as, plus the managed storage paths
• r4 space update -- Install the latest published @r4-sdk/cli release with the detected global package manager

r4 vault

Manage vault secrets.

• r4 vault create -- Create a checkpoint-signed vault from inline JSON or --body-file
• r4 vault create-item <vaultId> -- Create a checkpoint-signed vault item from inline JSON or --body-file
• r4 vault download-asset <vaultId> <assetId> [--output <path>] -- Download and locally decrypt a vault attachment
• r4 vault list -- List locally decrypted environment variables
• r4 vault get <name> -- Get a specific locally decrypted secret
• r4 vault list-items -- List vault item metadata without local decryption, including hidden parent-vault item shares
• r4 vault items --metadata-only -- Metadata-only alias when decryption is failing

r4 project

Manage projects.

• r4 project list -- List all projects
• r4 project get <id> -- Get project details
• r4 project create -- Create a new project
• r4 project add-vault -- Associate a vault with a project

r4 security-group

Manage tenant security groups.

• r4 security-group create -- Create a tenant security group with delegated tenant roles

r4 permissions

Manage asset permissions.

• r4 permissions security-groups -- List visible security groups from the permissions surface
• r4 permissions set <assetType> <id> -- Replace permissions for an asset from inline JSON or --body-file

r4 feedback

Submit structured product feedback.

• r4 feedback submit -- Store AGENT feedback about missing CLI, SDK, MCP, or machine-API capability

r4 run <command...>

Execute a command with vault secrets injected as environment variables.

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

Global Options

| Flag | Description | |--------------------|---------------------------------------------------| | --api-key <key> | API key (overrides R4_API_KEY env var and config)| | --profile <name> | CLI profile name (overrides R4_PROFILE) | | --project-id <id>| Optional project filter (overrides R4_PROJECT_ID env var) | | --base-url <url> | API base URL (default: https://r4.dev) | | --private-key-path <path> | Path to the local agent private key PEM | | --trust-store-path <path> | Path to the local signer trust-store JSON | | --json | Output as JSON for scripting and piping |

First Run

The simplest bootstrap path is:

r4 configure

That guided flow can:

• bootstrap a brand-new agent-only org and runtime keypair after you provide a saved Stripe pm_... payment method id and an initial credit amount of at least $20
• or save an existing access key, secret, and private-key path
• write split credentials to ~/.r4/profiles/<profile>/credentials.json
• default the managed key path to ~/.r4/profiles/<profile>/private-key.pem
• default the trust store to ~/.r4/profiles/<profile>/trust-store.json
• cache the resolved identity so r4 profile show / r4 space info can answer "who am I?" quickly

If you already have a handoff bundle and want the one-shot bootstrap path, you can still use:

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

That flow can read a CSV, .env, JSON, or plain-text credentials handoff, accept either a full apiKey or split accessKey + secretKey, register the matching public key with the machine API, save the resolved settings into the active profile, and run r4 doctor to confirm the runtime is healthy.

The CLI supports either R4_API_KEY or split R4_ACCESS_KEY + R4_SECRET_KEY environment variables. Saved credentials now live in named profiles, so you can switch with r4 profile use <name>.

The zero-trust runtime path still needs an AGENT-scoped API key plus a local private key. Provide the key path via --private-key-path, R4_PRIVATE_KEY_PATH, or let r4 configure / r4 agent init create the default managed profile key. Use --base-url or R4_BASE_URL when you need to point the CLI at a non-default environment. When the CLI notices that a newer published version exists, it now prints a friendly reminder before normal commands and points you at r4 space update. Operators should let the runtime complete that first public-key registration before they assign security-group, project, or direct vault access to the agent. Re-registering the same key is safe, and rotating to a different key is supported when the caller submits the replacement rewrappedVaultKeys batch for the active vault DEKs that key can reach. Official CLI registration requests also send X-R4-Agent-Hostname: <local hostname> so the platform Agents table can show where the active runtime key most recently initialized.

When decryption is failing but API access is otherwise correct, use r4 doctor, r4 vault list-items, or r4 vault items --metadata-only to separate metadata/access problems from local key or trust issues. Metadata-only item listing now also merges /vault/shared-items, so item-level shares from otherwise hidden parent vaults still appear with vaultName: "[Direct Item Share]". r4 auth whoami is the fastest way to confirm the current machine scope, tenant binding, and policy summary without exercising vault reads. r4 space info and r4 profile show expose the same identity view together with the credential, trust-store, and profile-directory paths. r4 machine request is the escape hatch when the raw machine API already has a route that the higher-level CLI has not wrapped yet. Common orchestration flows now have first-class helpers under budget, domain, billing, monitoring, and the checkpoint-signed vault create / vault create-item wrappers, but use --body-file for large signed checkpoint or permission payloads when you do drop down to the generic surface.

Vault attachments now have a first-class zero-trust download helper too:

r4 vault download-asset <vaultId> <assetId> --output ./artifact.bin
r4 --json vault download-asset <vaultId> <assetId>

That path verifies the signed attachment checkpoint, checks ciphertext and plaintext hashes/sizes, decrypts the blob locally with the vault DEK, and then writes the plaintext file to disk. JSON output returns metadata only.

Profile Storage

The CLI now keeps profile state under one consistent root:

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

• config.json stores non-secret profile settings and cached identity metadata
• credentials.json stores split accessKey / secretKey values with owner-only permissions
• the default managed private key and trust store live beside those credentials

Dependencies

Uses the published @r4-sdk/node package under the hood for API communication. Built with Commander, Chalk, ora, and cli-table3.

Development

pnpm run build    # Build with tsup
pnpm run dev      # Watch mode
pnpm run test     # Run CLI unit tests from test/
pnpm run test:pack # Verify npm publish excludes src/ and test/
pnpm run clean    # Remove lib/

The published CLI only ships the allowlisted lib/ and bin/ outputs from package.json#files. Source files under src/ and package-local tests under test/ stay out of the npm tarball.