npm package: @r4security/cli
Description: Official R4 CLI — manage vaults, projects, and secrets from the terminal
Latest version: 0.0.5

# @r4security/cli

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

## Installation

```bash
npm install -g @r4security/cli
```

Requires Node.js >= 18.0.0.

## Commands

### `r4 agent`
Bootstrap the local runtime.
- `r4 agent init` -- Read credentials, generate/reuse a private key, register the public key, 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 status` -- Show current authentication state
- `r4 auth whoami` -- Show the current profile identity and runtime target
- `r4 auth diagnose` -- Alias for `r4 doctor`

### `r4 doctor`
Verify API key auth, public-key registration, visible vaults, wrapped keys, and zero-trust health.

### `r4 profile`
Manage saved CLI profiles.
- `r4 profile list` -- List saved profiles
- `r4 profile use <name>` -- Switch the active profile

### `r4 vault`
Manage vault secrets.
- `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
- `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 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 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`
- generate `~/.r4/keys/<profile>.pem` if no local private key exists
- register the matching public key with the machine API
- save the resolved settings into the active profile
- 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 agent init` create the default profile key.
Use `--base-url` or `R4_BASE_URL` when you need to point the CLI at a
non-default environment.
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, but rotating to a different key is
currently blocked while vault-backed access still exists.

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.

## Dependencies

Uses the published `@r4security/sdk` 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.