@r4security/cli

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

Installation

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.

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 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

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.