@oriva/cli 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @oriva/cli
+
+Spec-driven CLI for the Oriva public API. Every endpoint in the OpenAPI spec becomes an `oriva <command>` subcommand — zero CLI code changes when new endpoints ship.
+
+For shell scripts, Claude Code agents, ops one-offs, and humans who'd rather not write Node TypeScript to hit the API.
+
+## Install
+
+```sh
+npm i -g @oriva/cli
+# or
+npx @oriva/cli <command>
+```
+
+Requires Node ≥ 18.
+
+## Auth
+
+The CLI looks for an API key in this order (highest precedence first):
+
+1. `--api-key=<value>` flag
+2. `ORIVA_API_KEY` env var
+3. `~/.config/oriva/config.json` → `profiles[<active>].apiKey`
+
+For most uses, export the env var:
+
+```sh
+export ORIVA_API_KEY=oriva_pk_live_…
+oriva getCurrentUser
+```
+
+For multi-environment work, write `~/.config/oriva/config.json`:
+
+```json
+{
+  "activeProfile": "default",
+  "profiles": {
+    "default": { "apiKey": "oriva_pk_live_…" },
+    "staging": {
+      "apiKey": "oriva_pk_test_…",
+      "baseUrl": "https://staging.api.oriva.io"
+    }
+  }
+}
+```
+
+Switch with `--profile=staging` or `ORIVA_PROFILE=staging`.
+
+## Usage
+
+```sh
+oriva --help                       # List all commands (grouped by OpenAPI tag)
+oriva <command> --help             # Per-command help: required + optional params
+oriva --version                    # CLI + spec version
+
+oriva getCurrentUser               # GET — pretty JSON
+oriva getCurrentUser --json        # Structured envelope { ok, status, data, error, request_id }
+oriva listProfiles --json | jq .
+
+# Request bodies — three input modes
+oriva createDeveloperApp --body='{"name":"my app"}'
+oriva createDeveloperApp --body=@app.json
+echo '{"name":"my app"}' | oriva createDeveloperApp --body=-
+```
+
+## Global flags
+
+| Flag                 | Purpose                                                              |
+| -------------------- | -------------------------------------------------------------------- |
+| `--api-key=<value>`  | One-off override of `ORIVA_API_KEY`                                  |
+| `--profile=<name>`   | Use a different config-file profile                                  |
+| `--base-url=<url>`   | Override the API base URL                                            |
+| `--spec=<url\|path>` | Use a different OpenAPI spec (default: bundled snapshot)             |
+| `--json`             | Emit `{ ok, status, data, error, request_id }` envelope (for agents) |
+| `--raw`              | Print body unchanged — no JSON pretty-print                          |
+| `--show-status`      | Print `HTTP <code> (request_id=<id>)` to stderr                      |
+| `--quiet`            | Suppress stderr progress lines                                       |
+| `--help`, `-h`       | Show this help (or per-command)                                      |
+| `--version`, `-V`    | Print CLI + spec version                                             |
+
+## Exit codes
+
+| Code | Meaning                     |
+| ---- | --------------------------- |
+| 0    | HTTP 2xx                    |
+| 1    | HTTP 4xx (client error)     |
+| 2    | HTTP 5xx or network failure |
+| 3    | Usage/parse error           |
+| 4    | Spec load failure           |
+
+## Error envelope (with `--json`)
+
+```json
+{
+  "ok": false,
+  "status": 401,
+  "data": null,
+  "error": { "code": "unauthenticated", "message": "..." },
+  "request_id": "req_ABC"
+}
+```
+
+Always parseable — same shape regardless of success/failure. Network errors return `status: 0`.
+
+## CLI vs SDK
+
+| Use case                           | Tool                                                                                      |
+| ---------------------------------- | ----------------------------------------------------------------------------------------- |
+| Node/TypeScript application code   | [`@oriva/sdk`](https://www.npmjs.com/package/@oriva/sdk) — typed client, IDE autocomplete |
+| Shell scripts, CI/CD, ops one-offs | `@oriva/cli` — no Node project needed                                                     |
+| Claude Code agents, MCP servers    | Either — CLI for general invocation, SDK for typed Node code                              |
+
+The CLI bundles its own OpenAPI snapshot so it works offline with sub-second cold start. The `peerDependency` on `@oriva/sdk` is optional and only declared for version-pinning hints — the CLI doesn't import the SDK at runtime.
+
+## License
+
+MIT

package/bin/oriva.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * `oriva` CLI bin shim.
+ *
+ * The compiled entry lives in dist/cli.js (ESM). We dynamic-import it so
+ * the shim itself stays valid CJS-safe Node script — works whether the
+ * installed Node uses ESM or CJS resolution.
+ */
+import('../dist/cli.js')
+  .then(({ run }) => run())
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write(`[oriva] fatal: ${err && err.message ? err.message : err}\n`);
+    process.exit(2);
+  });

package/dist/auth.d.ts

@@ -0,0 +1,23 @@
+export interface ResolvedAuth {
+    apiKey?: string;
+    baseUrl?: string;
+    /** Provenance for diagnostics — "flag" | "env" | "config:<profile>" | "none". */
+    source: string;
+}
+export interface ConfigProfile {
+    apiKey?: string;
+    baseUrl?: string;
+}
+export interface ConfigFile {
+    activeProfile?: string;
+    profiles?: Record<string, ConfigProfile>;
+}
+export interface ResolveAuthOptions {
+    flagApiKey?: string;
+    envApiKey?: string;
+    profile?: string;
+    /** Custom config path for tests. Defaults to ~/.config/oriva/config.json. */
+    configPath?: string;
+}
+export declare function resolveAuth(opts: ResolveAuthOptions): Promise<ResolvedAuth>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAqBjF"}

package/dist/auth.js

@@ -0,0 +1,49 @@
+/**
+ * API-key resolution for the `oriva` CLI.
+ *
+ * Precedence (highest wins):
+ *   1. --api-key=<key>                          (flag)
+ *   2. ORIVA_API_KEY env var
+ *   3. ~/.config/oriva/config.json
+ *      - if --profile=<name> set: profiles[<name>].apiKey
+ *      - else: profiles[activeProfile].apiKey
+ *      - else: profiles.default.apiKey
+ *   4. undefined (caller decides whether to warn)
+ *
+ * Config-file schema:
+ *   {
+ *     "activeProfile": "staging",
+ *     "profiles": {
+ *       "default": { "apiKey": "oriva_pk_live_..." },
+ *       "staging": { "apiKey": "oriva_pk_test_...", "baseUrl": "https://staging.api.oriva.io" }
+ *     }
+ *   }
+ *
+ * `baseUrl` can also live on a profile and is returned alongside the key.
+ */
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+export async function resolveAuth(opts) {
+    if (opts.flagApiKey)
+        return { apiKey: opts.flagApiKey, source: 'flag' };
+    if (opts.envApiKey)
+        return { apiKey: opts.envApiKey, source: 'env' };
+    const cfgPath = opts.configPath ?? resolve(homedir(), '.config', 'oriva', 'config.json');
+    let cfg;
+    try {
+        const text = await readFile(cfgPath, 'utf8');
+        cfg = JSON.parse(text);
+    }
+    catch {
+        // No config file or unreadable — fall through to "none".
+        return { source: 'none' };
+    }
+    const profiles = cfg.profiles ?? {};
+    const want = opts.profile ?? cfg.activeProfile ?? 'default';
+    const picked = profiles[want] ?? profiles.default;
+    if (picked?.apiKey) {
+        return { apiKey: picked.apiKey, baseUrl: picked.baseUrl, source: `config:${want}` };
+    }
+    return { source: 'none' };
+}

package/dist/cli.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `oriva` CLI entry point.
+ *
+ * Boot sequence:
+ *   1. parseArgs(process.argv.slice(2))
+ *   2. resolveAuth (flag → env → config-file)
+ *   3. Load OpenAPI spec (--spec / ORIVA_API_SPEC / bundled snapshot)
+ *   4. Extract operations
+ *   5. Dispatch:
+ *      - help → top-level help
+ *      - command-help → per-command help
+ *      - version → CLI + spec version
+ *      - command → coerce flags, read body, executeOperation, print result
+ *
+ * Exit codes:
+ *   0  2xx response (or help/version)
+ *   1  4xx response
+ *   2  5xx response or network failure
+ *   3  usage/parse error (bad flags, unknown command, missing required input)
+ *   4  spec load failure
+ *
+ * Ported from ultra-cli (~/ultra-network/packages/ultra-cli/src/cli.ts).
+ * Adds: --json envelope output, --profile + --api-key, config-file auth,
+ * bundled-snapshot default spec source.
+ */
+import { type MinimalOpenApiDoc } from './shared/loadSpec.js';
+import { renderEnvelope } from './output.js';
+export interface RunDeps {
+    argv?: string[];
+    env?: NodeJS.ProcessEnv;
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    fetchImpl?: typeof fetch;
+    /** Inject a spec for tests; skips loadSpec. */
+    specOverride?: MinimalOpenApiDoc;
+    /** Override the config-file path for tests. */
+    configPath?: string;
+}
+export declare function run(deps?: RunDeps): Promise<number>;
+export { renderEnvelope };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAiC,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAS7F,OAAO,EAAgB,cAAc,EAAE,MAAM,aAAa,CAAC;AAK3D,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,GAAG,CAAC,IAAI,GAAE,OAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAuI7D;AA6BD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/cli.js

@@ -0,0 +1,177 @@
+/**
+ * `oriva` CLI entry point.
+ *
+ * Boot sequence:
+ *   1. parseArgs(process.argv.slice(2))
+ *   2. resolveAuth (flag → env → config-file)
+ *   3. Load OpenAPI spec (--spec / ORIVA_API_SPEC / bundled snapshot)
+ *   4. Extract operations
+ *   5. Dispatch:
+ *      - help → top-level help
+ *      - command-help → per-command help
+ *      - version → CLI + spec version
+ *      - command → coerce flags, read body, executeOperation, print result
+ *
+ * Exit codes:
+ *   0  2xx response (or help/version)
+ *   1  4xx response
+ *   2  5xx response or network failure
+ *   3  usage/parse error (bad flags, unknown command, missing required input)
+ *   4  spec load failure
+ *
+ * Ported from ultra-cli (~/ultra-network/packages/ultra-cli/src/cli.ts).
+ * Adds: --json envelope output, --profile + --api-key, config-file auth,
+ * bundled-snapshot default spec source.
+ */
+import { loadSpec, bundledSnapshotPath } from './shared/loadSpec.js';
+import { extractOperations } from './shared/toolGenerator.js';
+import { executeOperation } from './shared/httpExecutor.js';
+import { parseArgs } from './parseArgs.js';
+import { renderTopLevelHelp, renderCommandHelp, renderVersion } from './help.js';
+import { coerceArgs } from './coerce.js';
+import { readBody } from './readBody.js';
+import { resolveAuth } from './auth.js';
+import { renderOutput, renderEnvelope } from './output.js';
+const CLI_VERSION = '0.1.0';
+const DEFAULT_BASE_URL = 'https://api.oriva.io';
+export async function run(deps = {}) {
+    const argv = deps.argv ?? process.argv.slice(2);
+    const env = deps.env ?? process.env;
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    const stdin = deps.stdin ?? process.stdin;
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (err) {
+        stderr.write(`Error: ${err.message}\n`);
+        return 3;
+    }
+    // Spec source precedence: --spec > ORIVA_API_SPEC > bundled snapshot.
+    const specSource = parsed.global.spec || (env.ORIVA_API_SPEC || '').trim() || bundledSnapshotPath();
+    const tagFilter = (env.ORIVA_API_TAGS || '')
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+    let doc;
+    try {
+        doc = deps.specOverride ?? (await loadSpec(specSource));
+    }
+    catch (err) {
+        stderr.write(`Failed to load OpenAPI spec from ${specSource}: ${err.message}\n`);
+        return 4;
+    }
+    const operations = extractOperations(doc, { tagFilter });
+    const opsByName = new Map(operations.map((o) => [o.name, o]));
+    if (parsed.kind === 'help') {
+        stdout.write(renderTopLevelHelp(operations));
+        stdout.write('\n');
+        return 0;
+    }
+    if (parsed.kind === 'version') {
+        stdout.write(renderVersion(CLI_VERSION, doc.info?.version));
+        stdout.write('\n');
+        return 0;
+    }
+    if (parsed.kind === 'command-help') {
+        const op = opsByName.get(parsed.command);
+        if (!op)
+            return unknownCommand(parsed.command, operations, stderr);
+        stdout.write(renderCommandHelp(op));
+        stdout.write('\n');
+        return 0;
+    }
+    // kind === 'command'
+    const op = opsByName.get(parsed.command);
+    if (!op)
+        return unknownCommand(parsed.command, operations, stderr);
+    // Resolve auth: flag > env > config-file.
+    const auth = await resolveAuth({
+        flagApiKey: parsed.global.apiKey,
+        envApiKey: (env.ORIVA_API_KEY || '').trim() || undefined,
+        profile: parsed.global.profile,
+        configPath: deps.configPath,
+    });
+    if (!auth.apiKey && !parsed.global.quiet) {
+        stderr.write('[oriva] WARNING: no API key resolved (flag → ORIVA_API_KEY → ~/.config/oriva/config.json) — call will likely 401.\n');
+    }
+    let args;
+    try {
+        args = coerceArgs(parsed.flags, op.inputSchema);
+    }
+    catch (err) {
+        stderr.write(`Argument error: ${err.message}\n`);
+        return 3;
+    }
+    try {
+        const body = await readBody(parsed.bodySource, stdin);
+        if (body !== undefined)
+            args.body = body;
+    }
+    catch (err) {
+        stderr.write(`Body error: ${err.message}\n`);
+        return 3;
+    }
+    if (op.hasBody && args.body === undefined && requiresBody(op)) {
+        stderr.write(`This command requires --body=<json|@file|->. Run \`oriva ${op.name} --help\`.\n`);
+        return 3;
+    }
+    const baseUrl = parsed.global.baseUrl ||
+        (env.ORIVA_API_BASE_URL || '').trim() ||
+        auth.baseUrl ||
+        doc.servers?.[0]?.url ||
+        DEFAULT_BASE_URL;
+    let result;
+    try {
+        result = await executeOperation(op, args, { baseUrl, apiKey: auth.apiKey, userAgent: `oriva-cli/${CLI_VERSION}` }, deps.fetchImpl);
+    }
+    catch (err) {
+        if (parsed.global.json) {
+            // Emit envelope-shaped error so agents can parse network failures uniformly.
+            const envelope = {
+                ok: false,
+                status: 0,
+                data: null,
+                error: { message: err.message, kind: 'network' },
+                request_id: undefined,
+            };
+            stdout.write(JSON.stringify(envelope, null, 2));
+            stdout.write('\n');
+        }
+        else {
+            stderr.write(`Network error: ${err.message}\n`);
+        }
+        return 2;
+    }
+    if (parsed.global.showStatus && !parsed.global.quiet) {
+        stderr.write(`HTTP ${result.status}${result.request_id ? ` (request_id=${result.request_id})` : ''}\n`);
+    }
+    stdout.write(renderOutput(result, { raw: parsed.global.raw, json: parsed.global.json }));
+    stdout.write('\n');
+    if (result.status >= 500)
+        return 2;
+    if (result.status >= 400)
+        return 1;
+    return 0;
+}
+function unknownCommand(name, operations, stderr) {
+    stderr.write(`Unknown command: ${name}\n`);
+    const suggestions = operations
+        .map((o) => o.name)
+        .filter((n) => n
+        .toLowerCase()
+        .startsWith(name.toLowerCase().slice(0, Math.max(3, Math.floor(name.length / 2)))))
+        .slice(0, 5);
+    if (suggestions.length) {
+        stderr.write(`Did you mean: ${suggestions.join(', ')}?\n`);
+    }
+    stderr.write('Run `oriva --help` to list commands.\n');
+    return 3;
+}
+function requiresBody(op) {
+    const required = op.inputSchema.required ?? [];
+    return required.includes('body');
+}
+// Re-export for tests + bin shim.
+export { renderEnvelope };

package/dist/coerce.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Coerce string CLI flags to the JSON types the API expects.
+ *
+ * Ported verbatim from ultra-cli (~/ultra-network/packages/ultra-cli/src/coerce.ts) —
+ * type-coercion semantics are universal.
+ */
+export declare function coerceArgs(rawFlags: Record<string, string | string[] | boolean>, inputSchema: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=coerce.d.ts.map

package/dist/coerce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../src/coerce.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,EACrD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB"}

package/dist/coerce.js

@@ -0,0 +1,45 @@
+/**
+ * Coerce string CLI flags to the JSON types the API expects.
+ *
+ * Ported verbatim from ultra-cli (~/ultra-network/packages/ultra-cli/src/coerce.ts) —
+ * type-coercion semantics are universal.
+ */
+export function coerceArgs(rawFlags, inputSchema) {
+    const props = inputSchema.properties ?? {};
+    const out = {};
+    for (const [k, v] of Object.entries(rawFlags)) {
+        const schema = props[k];
+        out[k] = coerceOne(v, schema);
+    }
+    return out;
+}
+function coerceOne(v, schema) {
+    if (typeof v === 'boolean')
+        return v;
+    if (Array.isArray(v))
+        return v.map((x) => coerceScalar(x, schema?.items ?? schema));
+    return coerceScalar(v, schema);
+}
+function coerceScalar(s, schema) {
+    const t = schema?.type;
+    if (t === 'integer') {
+        const n = Number.parseInt(s, 10);
+        if (Number.isNaN(n))
+            throw new Error(`Expected integer, got: ${s}`);
+        return n;
+    }
+    if (t === 'number') {
+        const n = Number(s);
+        if (Number.isNaN(n))
+            throw new Error(`Expected number, got: ${s}`);
+        return n;
+    }
+    if (t === 'boolean') {
+        if (s === 'true' || s === '1')
+            return true;
+        if (s === 'false' || s === '0')
+            return false;
+        throw new Error(`Expected boolean, got: ${s}`);
+    }
+    return s;
+}

package/dist/help.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Help text rendering for the `oriva` CLI.
+ *
+ * Ported from ultra-cli (~/ultra-network/packages/ultra-cli/src/help.ts);
+ * key deviation: group commands by OpenAPI `tags[0]` instead of path segment.
+ * The Oriva spec has 13 clean tags (Auth/Profiles/Groups/Entries/…) that map
+ * cleaner than path roots (which all start with `/api/v1/...`).
+ */
+import type { ExtractedOperation } from './shared/types.js';
+export declare function renderTopLevelHelp(operations: ExtractedOperation[]): string;
+export declare function renderCommandHelp(op: ExtractedOperation): string;
+export declare function renderVersion(cliVersion: string, specVersion: string | undefined): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AA8B5D,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,kBAAkB,EAAE,GAAG,MAAM,CA4B3E;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,kBAAkB,GAAG,MAAM,CA2ChE;AAsBD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEzF"}

package/dist/help.js

@@ -0,0 +1,121 @@
+/**
+ * Help text rendering for the `oriva` CLI.
+ *
+ * Ported from ultra-cli (~/ultra-network/packages/ultra-cli/src/help.ts);
+ * key deviation: group commands by OpenAPI `tags[0]` instead of path segment.
+ * The Oriva spec has 13 clean tags (Auth/Profiles/Groups/Entries/…) that map
+ * cleaner than path roots (which all start with `/api/v1/...`).
+ */
+const HEADER = `oriva — Oriva public API CLI
+
+A spec-driven wrapper over every operation in the @oriva/sdk surface. Every
+endpoint becomes a subcommand. Use \`oriva <command> --help\` for per-command
+flags. Command names match @oriva/sdk function names 1:1.
+
+ENVIRONMENT
+  ORIVA_API_KEY        Bearer key (oriva_pk_live_… / oriva_pk_test_…)
+  ORIVA_API_SPEC       OpenAPI source (default: bundled snapshot)
+  ORIVA_API_BASE_URL   Override server base URL (default: https://api.oriva.io)
+  ORIVA_API_TAGS       CSV tag filter for which operations are exposed
+
+CONFIG FILE
+  ~/.config/oriva/config.json  Multi-profile auth — see README
+
+GLOBAL FLAGS
+  --api-key=<key>      Override ORIVA_API_KEY for this invocation
+  --profile=<name>     Select a config-file profile (default: activeProfile)
+  --spec=<url|path>    Override the spec source for this invocation
+  --base-url=<url>     Override the base URL for this invocation
+  --show-status        Print HTTP status + request_id to stderr
+  --raw                Print response body unchanged (no JSON pretty-print)
+  --json               Emit { ok, status, data, error, request_id } envelope
+  --quiet              Suppress progress lines on stderr
+  --help, -h           Show this help (or per-command help)
+  --version, -V        Print CLI + spec version
+`;
+export function renderTopLevelHelp(operations) {
+    const out = [HEADER, 'COMMANDS'];
+    if (operations.length === 0) {
+        out.push('  (no operations available — check ORIVA_API_SPEC)');
+        return out.join('\n');
+    }
+    // Group by first OpenAPI tag; ops without tags go to 'misc'.
+    const groups = new Map();
+    for (const op of operations) {
+        const group = op.tags?.[0] || 'misc';
+        if (!groups.has(group))
+            groups.set(group, []);
+        groups.get(group).push(op);
+    }
+    const nameWidth = Math.min(40, Math.max(...operations.map((o) => o.name.length)));
+    for (const [group, ops] of [...groups.entries()].sort()) {
+        out.push('');
+        out.push(`  ${group}`);
+        for (const op of ops.sort((a, b) => a.name.localeCompare(b.name))) {
+            const padded = op.name.padEnd(nameWidth);
+            out.push(`    ${padded}  ${op.description}`);
+        }
+    }
+    out.push('');
+    out.push('Run `oriva <command> --help` for input details.');
+    return out.join('\n');
+}
+export function renderCommandHelp(op) {
+    const out = [];
+    out.push(`oriva ${op.name}`);
+    out.push('');
+    out.push(`  ${op.description}`);
+    out.push(`  ${op.method.toUpperCase()} ${op.pathTemplate}`);
+    if (op.tags?.length) {
+        out.push(`  tags: ${op.tags.join(', ')}`);
+    }
+    out.push('');
+    const schema = op.inputSchema;
+    const required = new Set(schema.required ?? []);
+    const props = schema.properties ?? {};
+    if (op.pathParams.length) {
+        out.push('PATH PARAMETERS (required)');
+        for (const name of op.pathParams) {
+            out.push(formatParam(name, props[name], required.has(name)));
+        }
+        out.push('');
+    }
+    if (op.queryParams.length) {
+        out.push('QUERY PARAMETERS');
+        for (const name of op.queryParams) {
+            out.push(formatParam(name, props[name], required.has(name)));
+        }
+        out.push('');
+    }
+    if (op.hasBody) {
+        out.push('REQUEST BODY');
+        out.push(`  --body=<json> | --body=@path/to/file.json | --body=-  (stdin)`);
+        out.push(`  Content-Type: ${op.bodyContentType || 'application/json'}`);
+        if (required.has('body'))
+            out.push('  (required)');
+        out.push('');
+    }
+    out.push('EXAMPLE');
+    out.push(formatExample(op));
+    return out.join('\n');
+}
+function formatParam(name, schema, isRequired) {
+    const tag = isRequired ? ' (required)' : '';
+    const type = schema?.type ? ` <${schema.type}>` : '';
+    const desc = schema?.description ? `  — ${schema.description}` : '';
+    const enumVals = schema?.enum?.length ? `  [${schema.enum.join('|')}]` : '';
+    return `  --${name}${type}${tag}${enumVals}${desc}`;
+}
+function formatExample(op) {
+    const parts = ['  oriva', op.name];
+    for (const p of op.pathParams)
+        parts.push(`--${p}=<${p}>`);
+    for (const q of op.queryParams.slice(0, 2))
+        parts.push(`--${q}=<value>`);
+    if (op.hasBody)
+        parts.push(`--body='{"…":"…"}'`);
+    return parts.join(' ');
+}
+export function renderVersion(cliVersion, specVersion) {
+    return `oriva ${cliVersion}\nspec  ${specVersion ?? '(unknown)'}`;
+}

package/dist/output.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Output rendering for the `oriva` CLI.
+ *
+ * Three modes:
+ *   default: pretty-printed JSON of the response body
+ *   --raw:   response body unchanged (no re-serialization)
+ *   --json:  agent-friendly envelope
+ *            { ok, status, data, error, request_id, url?, method? }
+ *
+ * The envelope is always parseable regardless of HTTP status — agents calling
+ * the CLI in tight loops want `JSON.parse(stdout).ok` not `if (exit === 0) ...`.
+ */
+import type { ExecuteResult } from './shared/httpExecutor.js';
+export interface OutputOptions {
+    raw?: boolean;
+    json?: boolean;
+}
+export interface Envelope {
+    ok: boolean;
+    status: number;
+    data: unknown;
+    error: unknown;
+    request_id?: string;
+    url?: string;
+    method?: string;
+}
+export declare function renderEnvelope(result: ExecuteResult): Envelope;
+export declare function renderOutput(result: ExecuteResult, opts: OutputOptions): string;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,QAAQ,CAyB9D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAQ/E"}