@r4-sdk/cli 1.0.0

package/README.md

@@ -0,0 +1,213 @@
+# @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`
+- 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, 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 and saves it 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 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 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 project add-vault` -- Associate a vault with a project
+- `r4 project set-agents <projectId>` -- Replace explicit project agent membership
+
+### `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
+- 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.
+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.
+
+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.
+`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.
+
+## 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/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.

package/bin/r4.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../lib/index.js').catch(() => {
+  console.error('Please build @r4-sdk/cli first: pnpm run build')
+  process.exit(1)
+})