@r4security/cli 0.0.2 → 0.0.5

package/README.md

@@ -12,16 +12,32 @@ 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` -- Configure API key credentials
-- `r4 auth logout` -- Remove stored credentials
+- `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.
@@ -42,19 +58,46 @@ r4 run --prefix R4 -- docker compose up
 | 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) |
-| `--dev`            | Use `https://dev.r4.dev` unless an explicit base URL is set |
 | `--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            |
 
-The CLI now follows the same zero-trust agent flow as `@r4security/sdk`, so it needs an
-AGENT-scoped API key plus a local private key. Provide the key path via
-`--private-key-path`, `R4_PRIVATE_KEY_PATH`, or `~/.r4/config.json`.
-Set `R4_DEV=1` or save `dev: true` via `r4 auth login --dev` to default to
-`https://dev.r4.dev`. Any explicit `--base-url`, `R4_BASE_URL`, or saved
-`baseUrl` still wins over dev mode.
+## 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
 
@@ -65,6 +108,11 @@ Uses the published `@r4security/sdk` package under the hood for API communicatio
 ```bash
 pnpm run build    # Build with tsup
 pnpm run dev      # Watch mode
-pnpm run test     # Run CLI runtime-config tests
+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.