npm package: @r4-sdk/cli
Description: Official R4 CLI — manage vaults, projects, and secrets from the terminal
Latest version: 1.0.4

# @r4-sdk/cli

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

## Installation

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```text
~/.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

```bash
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.