@alvera-ai/platform-sdk 0.7.3 → 0.9.0

package/README.md

@@ -10,6 +10,8 @@ tables, action status updaters, AI agents — with full type safety.
 ```bash
 npm install @alvera-ai/platform-sdk
 # or
+bun add @alvera-ai/platform-sdk
+# or
 pnpm add @alvera-ai/platform-sdk
 ```
 
@@ -141,25 +143,30 @@ The CLI resolves a base URL with this precedence (highest first):
 
 Adding, renaming, or removing environments happens in the platform repo (the
 `servers/0` function in `lib/platform_api/api_spec.ex`); rerun
-`pnpm regen` in the SDK to pick up the change.
+`bun run regen` in the SDK to pick up the change.
 
 ## Resources
 
-| Resource                | Operations                                  |
-|-------------------------|---------------------------------------------|
-| `ping`                   | health check                                                                 |
-| `sessions`               | `verify`                                                                     |
-| `datasets`               | `search`                                                                     |
-| `datalakes`              | `list`, `get`, `create`                                                      |
-| `dataSources`            | `list`, `create`, `update`                                                   |
-| `tools`                  | `list`, `get`, `create`, `update`, `delete`                                  |
-| `genericTables`          | `list`, `create`                                                             |
-| `actionStatusUpdaters`   | `list`, `create`, `update`                                                   |
-| `aiAgents`               | `list`, `get`, `create`, `update`, `delete`                                  |
-| `connectedApps`          | `list`, `get`, `create`, `update`, `syncRoutes`, `resolvePage`, `updateMessageTracking` |
-| `dataActivationClients`  | `ingest`, `ingestFile`, `createUploadLink`                                   |
-| `mdm`                    | `verify`                                                                     |
-| `workflows`              | `execute`                                                                    |
+| Resource                     | Operations                                                                                                                                  |
+|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| `ping`                       | health check                                                                                                                                |
+| `sessions`                   | `verify`                                                                                                                                    |
+| `auth`                       | `signUp`                                                                                                                                    |
+| `admin`                      | `confirmUser`                                                                                                                               |
+| `tenants`                    | `list`, `create`                                                                                                                            |
+| `invitations`                | `list`, `create`, `accept`                                                                                                                  |
+| `datasets`                   | `search`, `metadata`, `createUserSearch`                                                                                                    |
+| `datalakes`                  | `list`, `get`, `create`, `metadata`, `migrate`, `createUploadLink`, `createDownloadLink`                                                    |
+| `dataSources`                | `list`, `create`, `update`                                                                                                                  |
+| `tools`                      | `list`, `get`, `create`, `update`, `delete`, `testInvocation`                                                                               |
+| `genericTables`              | `list`, `create`                                                                                                                            |
+| `actionStatusUpdaters`       | `list`, `create`, `update`                                                                                                                  |
+| `aiAgents`                   | `list`, `get`, `create`, `update`, `delete`                                                                                                 |
+| `connectedApps`              | `list`, `get`, `create`, `update`, `syncRoutes`, `resolvePage`, `updateMessageTracking`                                                     |
+| `dataActivationClients`      | `list`, `get`, `create`, `update`, `delete`, `metadata`, `runManually`, `ingest`, `ingestFile`, `logs.list`, `logs.get`                     |
+| `interoperabilityContracts`  | `list`, `get`, `create`, `update`, `delete`, `metadata`, `run`                                                                              |
+| `mdm`                        | `verify`                                                                                                                                    |
+| `workflows`                  | `list`, `get`, `create`, `update`, `delete`, `metadata`, `execute`, `run`, `workflowLogs.list/get/download`, `batchLogs.list/get/start/stop/refresh` |
 
 Tenant and datalake provisioning are performed by Alvera admins — contact your
 representative to onboard a new tenant.
@@ -290,12 +297,11 @@ git commit -am "feat(api): …"
 
 # in this repo
 cp ../platform/openapi.yaml spec/openapi.yaml
-pnpm regen        # gen-environments + codegen + check-coverage
-pnpm build        # compile to dist/
+bun run regen     # gen-environments + codegen + check-coverage
 git commit -am "chore: sync openapi spec"
 ```
 
-`pnpm regen` runs `gen-environments` (rebuilds
+`bun run regen` runs `gen-environments` (rebuilds
 `src/environments.generated.ts` from `servers[]`), then `codegen`, then
 `check-coverage`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alvera-ai/platform-sdk",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "Typed SDK for the Alvera platform API — manage data sources, tools, generic tables, AI agents, and action status updaters.",
   "type": "module",
   "sideEffects": false,
@@ -24,15 +24,14 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.20.0",
   "scripts": {
     "gen-environments": "tsx scripts/gen-environments.ts",
     "codegen": "openapi-ts && tsx scripts/patch-generated.ts",
     "check-coverage": "tsx scripts/check-sdk-coverage.ts",
-    "regen": "pnpm gen-environments && pnpm codegen && pnpm check-coverage",
+    "regen": "bun run gen-environments && bun run codegen && bun run check-coverage",
     "typecheck": "tsc --noEmit && tsc --noEmit -p scripts/tsconfig.json",
     "clean": "rm -rf src/generated src/environments.generated.ts",
-    "prepare": "pnpm gen-environments && pnpm codegen && pnpm check-coverage"
+    "prepare": "bun run gen-environments && bun run codegen && bun run check-coverage"
   },
   "dependencies": {
     "commander": "14.0.3",

package/src/cli/auth.ts

@@ -0,0 +1,174 @@
+import { Command } from 'commander';
+import { createSession, createUnvalidatedPlatformApi, revokeSession } from '../client.js';
+import {
+  CONFIG_PATHS,
+  ENVIRONMENTS,
+  clearProfileCreds,
+  getProfileName,
+  readProfileConfig,
+  resolveProfile,
+  writeProfileConfig,
+  writeProfileCreds,
+} from '../config.js';
+import { type GlobalOpts, authedApi, die, out, prompt, run } from './helpers.js';
+
+const ENVIRONMENT_NAMES = Object.keys(ENVIRONMENTS);
+
+export function register(program: Command): void {
+  program
+    .command('configure')
+    .description('Interactively set defaults (environment, tenant, email) for a profile')
+    .action(async () => {
+      const profile = getProfileName(program.opts<GlobalOpts>().profile);
+      const current = resolveProfile(profile);
+      const currentCfg = readProfileConfig(profile);
+
+      const options = ENVIRONMENT_NAMES.map(
+        (name) => `${name} (${ENVIRONMENTS[name as keyof typeof ENVIRONMENTS].base_url})`,
+      ).join(', ');
+      const defaultChoice = currentCfg.environment ?? current.environment;
+      const envInput =
+        (await prompt(`Environment [${defaultChoice}] — one of: ${options}, or a custom URL: `)) ||
+        defaultChoice;
+
+      const patch: { environment?: string; base_url?: string; tenant_slug?: string; email?: string } = {};
+      const unset: Array<'environment' | 'base_url'> = [];
+      if (ENVIRONMENT_NAMES.includes(envInput)) {
+        patch.environment = envInput;
+        unset.push('base_url');
+      } else if (/^https?:\/\//.test(envInput)) {
+        patch.base_url = envInput;
+        unset.push('environment');
+      } else {
+        die(
+          `"${envInput}" is not a known environment or a URL. ` +
+            `Valid: ${ENVIRONMENT_NAMES.join(', ')} or http(s)://…`,
+        );
+      }
+
+      patch.tenant_slug =
+        (await prompt(`Default tenant slug [${current.tenantSlug ?? ''}]: `)) || current.tenantSlug || '';
+      patch.email = (await prompt(`Email [${current.email ?? ''}]: `)) || current.email || '';
+      writeProfileConfig(profile, patch, unset);
+      process.stderr.write(`Saved profile "${profile}" → ${CONFIG_PATHS.config}\n`);
+    });
+
+  program
+    .command('login')
+    .description('Exchange credentials for a session token and store it')
+    .option('--email <email>')
+    .option('--password <password>')
+    .option('--tenant <slug>')
+    .option('--base-url <url>')
+    .option('--expires-in <seconds>', 'session duration (default 86400, max 2592000)')
+    .action(async (opts: Record<string, string>) => {
+      const profile = getProfileName(program.opts<GlobalOpts>().profile);
+      const current = resolveProfile(profile);
+      const baseUrl = opts.baseUrl ?? current.baseUrl;
+      const email = opts.email ?? current.email ?? (await prompt('Email: '));
+      const password = opts.password ?? process.env.ALVERA_PASSWORD ?? (await prompt('Password: ', { hidden: true }));
+      const tenant = opts.tenant ?? current.tenantSlug ?? (await prompt('Tenant slug: '));
+      if (!email || !password || !tenant) die('email, password, and tenant are required');
+
+      await run(async () => {
+        const session = await createSession({
+          baseUrl,
+          email,
+          password,
+          tenantSlug: tenant,
+          expiresIn: opts.expiresIn ? Number(opts.expiresIn) : undefined,
+        });
+        writeProfileConfig(profile, {
+          ...(opts.baseUrl ? { base_url: baseUrl } : {}),
+          tenant_slug: tenant,
+          email,
+        });
+        clearProfileCreds(profile);
+        writeProfileCreds(profile, {
+          session_token: session.sessionToken,
+          expires_at: session.expiresAt ?? '',
+        });
+        const tenantLabel = session.tenant ? `tenant "${session.tenant.slug}"` : 'no tenant';
+        process.stderr.write(
+          `Logged in as ${email} → ${tenantLabel} (profile "${profile}").\n` +
+            `Token stored in ${CONFIG_PATHS.credentials}\n` +
+            (session.expiresAt ? `Expires at ${session.expiresAt}\n` : ''),
+        );
+        return undefined;
+      });
+    });
+
+  program
+    .command('logout')
+    .description('Revoke the current session and clear stored credentials')
+    .action(async () => {
+      const profile = getProfileName(program.opts<GlobalOpts>().profile);
+      const resolved = resolveProfile(profile);
+      if (resolved.sessionToken) {
+        createUnvalidatedPlatformApi({ baseUrl: resolved.baseUrl, sessionToken: resolved.sessionToken });
+        try {
+          await revokeSession();
+        } catch {
+          // Token may already be invalid/expired — clear local state anyway.
+        }
+      }
+      clearProfileCreds(profile);
+      process.stderr.write(`Cleared credentials for profile "${profile}".\n`);
+    });
+
+  program
+    .command('whoami')
+    .description('Print the current profile configuration')
+    .action(() => {
+      const profile = getProfileName(program.opts<GlobalOpts>().profile);
+      const resolved = resolveProfile(profile);
+      out({
+        profile: resolved.profile,
+        environment: resolved.environment,
+        baseUrl: resolved.baseUrl,
+        tenantSlug: resolved.tenantSlug,
+        email: resolved.email,
+        hasSessionToken: Boolean(resolved.sessionToken),
+        expiresAt: resolved.expiresAt,
+        hasApiKey: Boolean(resolved.apiKey),
+      });
+    });
+
+  program
+    .command('set-api-key')
+    .description('Store an API key for the current profile (used instead of session token)')
+    .argument('[key]', 'API key (omit to read from prompt or ALVERA_API_KEY)')
+    .action(async (key?: string) => {
+      const profile = getProfileName(program.opts<GlobalOpts>().profile);
+      const apiKey = key ?? process.env.ALVERA_API_KEY ?? (await prompt('API key: ', { hidden: true }));
+      if (!apiKey) die('API key is required');
+      clearProfileCreds(profile);
+      writeProfileCreds(profile, { api_key: apiKey });
+      process.stderr.write(
+        `API key stored for profile "${profile}" → ${CONFIG_PATHS.credentials}\n` +
+          `(session token cleared)\n`,
+      );
+    });
+
+  program
+    .command('ping')
+    .description('Health check')
+    .action(async () => {
+      await run(async () => {
+        const { api } = authedApi(program.opts<GlobalOpts>());
+        const { data } = await api.ping();
+        return data;
+      });
+    });
+
+  program
+    .command('sessions-verify')
+    .description('Verify the current session token via the API')
+    .action(async () => {
+      await run(async () => {
+        const { api } = authedApi(program.opts<GlobalOpts>());
+        const { data } = await api.sessions.verify();
+        return data;
+      });
+    });
+}

package/src/cli/env.ts

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import {
+  DEFAULT_ENVIRONMENT,
+  ENVIRONMENTS,
+  getProfileName,
+  resolveProfile,
+  writeProfileConfig,
+} from '../config.js';
+import { type GlobalOpts, die, out } from './helpers.js';
+
+const ENVIRONMENT_NAMES = Object.keys(ENVIRONMENTS);
+
+export function register(program: Command): void {
+  const envCmd = program
+    .command('env')
+    .description('List and switch Alvera API environments');
+
+  envCmd
+    .command('list')
+    .description('List available environments (from spec/openapi.yaml)')
+    .action(() => {
+      const profile = getProfileName(program.opts<GlobalOpts>().profile);
+      const resolved = resolveProfile(profile);
+      out(
+        ENVIRONMENT_NAMES.map((name) => ({
+          name,
+          baseUrl: ENVIRONMENTS[name as keyof typeof ENVIRONMENTS].base_url,
+          description: ENVIRONMENTS[name as keyof typeof ENVIRONMENTS].description,
+          default: name === DEFAULT_ENVIRONMENT,
+          active: name === resolved.environment,
+        })),
+      );
+    });
+
+  envCmd
+    .command('use <name>')
+    .description('Persist the selected environment to the profile (clears any custom base_url)')
+    .action((name: string) => {
+      if (!ENVIRONMENT_NAMES.includes(name)) {
+        die(`unknown environment "${name}". Valid: ${ENVIRONMENT_NAMES.join(', ')}`);
+      }
+      const profile = getProfileName(program.opts<GlobalOpts>().profile);
+      writeProfileConfig(profile, { environment: name }, ['base_url']);
+      process.stderr.write(
+        `Profile "${profile}" now uses environment "${name}" ` +
+          `(${ENVIRONMENTS[name as keyof typeof ENVIRONMENTS].base_url}).\n`,
+      );
+    });
+}

package/src/cli/helpers.ts

@@ -0,0 +1,128 @@
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { Command } from 'commander';
+import { ValiError } from 'valibot';
+import { createUnvalidatedPlatformApi } from '../client.js';
+import { getProfileName, resolveProfile } from '../config.js';
+
+export interface GlobalOpts {
+  profile?: string;
+  env?: string;
+}
+
+export function out(value: unknown): void {
+  process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+}
+
+export function die(message: string, code = 1): never {
+  process.stderr.write(`alvera: ${message}\n`);
+  process.exit(code);
+}
+
+export async function prompt(question: string, { hidden = false } = {}): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  if (!hidden) {
+    return new Promise((resolve) => rl.question(question, (ans) => {
+      rl.close();
+      resolve(ans);
+    }));
+  }
+  const anyRl = rl as unknown as { _writeToOutput: (s: string) => void };
+  const originalWrite = anyRl._writeToOutput.bind(rl);
+  anyRl._writeToOutput = (s: string) => {
+    if (s.includes(question)) originalWrite(s);
+    else originalWrite('');
+  };
+  return new Promise((resolve) => rl.question(question, (ans) => {
+    rl.close();
+    process.stderr.write('\n');
+    resolve(ans);
+  }));
+}
+
+export function readBody(body: string | undefined, bodyFile: string | undefined): Record<string, unknown> {
+  if (body && bodyFile) die('use only one of --body or --body-file');
+  let raw: string;
+  if (body) raw = body;
+  else if (bodyFile === '-') raw = readFileSync(0, 'utf8');
+  else if (bodyFile) raw = readFileSync(bodyFile, 'utf8');
+  else die('missing request body (pass --body <json> or --body-file <path>)');
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      die('body must be a JSON object');
+    }
+    return parsed;
+  } catch (err) {
+    die(`invalid JSON in body: ${(err as Error).message}`);
+  }
+}
+
+export function resolveTenant(explicit: string | undefined, profileTenant: string | null): string {
+  const tenant = explicit ?? profileTenant;
+  if (!tenant) die('tenant slug required (pass as argument or set `tenant_slug` in the profile)');
+  return tenant;
+}
+
+export function authedApi(opts: GlobalOpts) {
+  const profile = getProfileName(opts.profile);
+  const resolved = resolveProfile(profile);
+
+  if (resolved.apiKey) {
+    return {
+      api: createUnvalidatedPlatformApi({ baseUrl: resolved.baseUrl, apiKey: resolved.apiKey }),
+      resolved,
+    };
+  }
+
+  if (!resolved.sessionToken) {
+    die(
+      `no credentials for profile "${profile}". ` +
+        `Run \`alvera login --profile ${profile}\`, set ALVERA_SESSION_TOKEN, or set ALVERA_API_KEY.`,
+    );
+  }
+  if (resolved.expiresAt && new Date(resolved.expiresAt) < new Date()) {
+    die(
+      `session for profile "${profile}" expired at ${resolved.expiresAt}. ` +
+        `Run \`alvera login --profile ${profile}\` to refresh.`,
+    );
+  }
+  return {
+    api: createUnvalidatedPlatformApi({ baseUrl: resolved.baseUrl, sessionToken: resolved.sessionToken }),
+    resolved,
+  };
+}
+
+export async function run(fn: () => Promise<unknown>): Promise<void> {
+  try {
+    const result = await fn();
+    if (result !== undefined) out(result);
+  } catch (err) {
+    die(formatError(err));
+  }
+}
+
+export function formatError(err: unknown): string {
+  if (err instanceof ValiError) {
+    const lines = err.issues.map((issue) => {
+      const path = (issue.path ?? [])
+        .map((p: { key?: unknown }) => String(p.key ?? '?'))
+        .join('.') || '(root)';
+      return `  ${path}: ${issue.message}`;
+    });
+    return `validation failed:\n${lines.join('\n')}`;
+  }
+  if (err instanceof Error) return err.message;
+  if (err && typeof err === 'object') {
+    const detail = (err as { errors?: { detail?: unknown } }).errors?.detail;
+    if (typeof detail === 'string') return detail;
+    return JSON.stringify(err, null, 2);
+  }
+  return String(err);
+}
+
+export function bodyOption(cmd: Command): Command {
+  return cmd
+    .option('--body <json>', 'request body as a JSON string')
+    .option('--body-file <path>', 'path to a JSON file (or "-" for stdin)');
+}

package/src/cli/init.ts

@@ -0,0 +1,123 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { resolve } from 'node:path';
+import { Command } from 'commander';
+
+interface InitField {
+  key: string;
+  label: string;
+  default?: string;
+}
+type InitSection = { header: string; fields: InitField[] }
+
+const DB_KEYS = ['HOST', 'PORT', 'NAME', 'SCHEMA', 'AUTH_METHOD', 'USER', 'PASS', 'ENABLE_SSL'] as const;
+const DB_LABELS = ['host', 'port', 'database name', 'schema', 'auth method', 'user', 'password', 'enable SSL'] as const;
+const DB_DEFAULTS: Record<string, string> = { PORT: '5432', SCHEMA: 'public', AUTH_METHOD: 'password', ENABLE_SSL: 'false' };
+
+function dbSection(label: string, prefix: string): InitSection {
+  return {
+    header: label,
+    fields: DB_KEYS.map((k, i) => ({
+      key: `${prefix}_${k}`,
+      label: `${label} — ${DB_LABELS[i]}`,
+      default: DB_DEFAULTS[k],
+    })),
+  };
+}
+
+const STORAGE_KEYS = ['TYPE', 'REGION', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY', 'ENDPOINT', 'BUCKET'] as const;
+const STORAGE_LABELS = ['type (aws/r2)', 'region', 'access key ID', 'secret access key', 'endpoint', 'bucket'] as const;
+
+function storageSection(label: string, prefix: string): InitSection {
+  return {
+    header: label,
+    fields: STORAGE_KEYS.map((k, i) => ({
+      key: `${prefix}_${k}`,
+      label: `${label} — ${STORAGE_LABELS[i]}`,
+      default: k === 'TYPE' ? 'aws' : undefined,
+    })),
+  };
+}
+
+async function collectAndWrite(sections: InitSection[], outPath: string): Promise<void> {
+  const allFields = sections.flatMap((s) => s.fields);
+
+  let answers: string[];
+  if (process.stdin.isTTY) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    const ask = (q: string): Promise<string> =>
+      new Promise((res) => rl.question(q, (ans) => res(ans)));
+    answers = [];
+    for (const field of allFields) {
+      const dflt = field.default ?? '';
+      const suffix = dflt ? ` [${dflt}]` : '';
+      answers.push(await ask(`${field.label}${suffix}: `));
+    }
+    rl.close();
+  } else {
+    const raw = readFileSync(0, 'utf8');
+    answers = raw.split('\n');
+  }
+
+  const lines: string[] = [];
+  let idx = 0;
+  for (const section of sections) {
+    if (lines.length > 0) lines.push('');
+    lines.push(`# ${section.header}`);
+    for (const field of section.fields) {
+      const dflt = field.default ?? '';
+      const answer = (answers[idx++] ?? '').trim();
+      lines.push(`${field.key}=${answer || dflt}`);
+    }
+  }
+
+  const abs = resolve(process.cwd(), outPath);
+  writeFileSync(abs, lines.join('\n') + '\n');
+  process.stderr.write(`Wrote ${abs}\n`);
+}
+
+export function register(program: Command): void {
+  const initCmd = program.command('init').description('Generate a .env configuration file');
+
+  initCmd
+    .command('connected-app')
+    .description('Generate .env for SDK / connected-app integration')
+    .option('-o, --output <path>', 'output file path', '.env')
+    .action(async (opts: { output: string }) => {
+      await collectAndWrite([
+        {
+          header: 'Alvera connected-app configuration',
+          fields: [
+            { key: 'ALVERA_BASE_URL', label: 'Base URL', default: 'https://api.alvera.ai' },
+            { key: 'ALVERA_TENANT', label: 'Tenant slug' },
+            { key: 'ALVERA_DATALAKE', label: 'Datalake slug' },
+            { key: 'ALVERA_CONNECTED_APP', label: 'Connected app slug' },
+          ],
+        },
+      ], opts.output);
+    });
+
+  initCmd
+    .command('infra-setup')
+    .description('Generate .env for datalake infrastructure (databases + object storage)')
+    .option('-o, --output <path>', 'output file path', '.env')
+    .action(async (opts: { output: string }) => {
+      await collectAndWrite([
+        {
+          header: 'Datalake',
+          fields: [
+            { key: 'ALVERA_DATALAKE_NAME', label: 'Datalake name' },
+            { key: 'ALVERA_DATALAKE_DATA_DOMAIN', label: 'Data domain' },
+            { key: 'ALVERA_DATALAKE_TIMEZONE', label: 'Timezone', default: 'UTC' },
+            { key: 'ALVERA_DATALAKE_POOL_SIZE', label: 'Pool size', default: '10' },
+          ],
+        },
+        dbSection('Database — Unregulated Reader', 'ALVERA_DB_UNREG_READER'),
+        dbSection('Database — Unregulated Writer', 'ALVERA_DB_UNREG_WRITER'),
+        dbSection('Database — Regulated Reader', 'ALVERA_DB_REG_READER'),
+        dbSection('Database — Regulated Writer', 'ALVERA_DB_REG_WRITER'),
+        storageSection('Storage — Unregulated', 'ALVERA_STORAGE_UNREG'),
+        storageSection('Storage — Regulated', 'ALVERA_STORAGE_REG'),
+      ], opts.output);
+    });
+}

package/src/cli/raw.ts

@@ -0,0 +1,65 @@
+import { Command } from 'commander';
+import { getProfileName, resolveProfile } from '../config.js';
+import { type GlobalOpts, bodyOption, die, out, readBody } from './helpers.js';
+
+const ALLOWED_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const;
+
+export function register(program: Command): void {
+  bodyOption(
+    program
+      .command('raw <method> <path>')
+      .description('Send an authenticated HTTP request bypassing SDK validation')
+      .option('--no-parse', 'print raw response text instead of pretty-printing JSON'),
+  )
+    .action(
+      async (
+        method: string,
+        path: string,
+        opts: { body?: string; bodyFile?: string; parse?: boolean },
+      ) => {
+        const upper = method.toUpperCase();
+        if (!ALLOWED_METHODS.includes(upper as (typeof ALLOWED_METHODS)[number])) {
+          die(`invalid method "${method}". Allowed: ${ALLOWED_METHODS.join(', ')}`);
+        }
+
+        const globalOpts = program.opts<GlobalOpts>();
+        const profile = getProfileName(globalOpts.profile);
+        const resolved = resolveProfile(profile);
+        if (!resolved.sessionToken && !resolved.apiKey) {
+          die(
+            `no credentials for profile "${profile}". ` +
+              `Run \`alvera login\`, set ALVERA_SESSION_TOKEN, or set ALVERA_API_KEY.`,
+          );
+        }
+
+        const url = `${resolved.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+        const headers: Record<string, string> = resolved.apiKey
+          ? { 'X-API-Key': resolved.apiKey }
+          : { Authorization: `Bearer ${resolved.sessionToken!}` };
+
+        let fetchBody: string | undefined;
+        if (opts.body || opts.bodyFile) {
+          const parsed = readBody(opts.body, opts.bodyFile);
+          fetchBody = JSON.stringify(parsed);
+          headers['Content-Type'] = 'application/json';
+        }
+
+        const resp = await fetch(url, { method: upper, headers, body: fetchBody });
+        const text = await resp.text();
+
+        if (!resp.ok) {
+          die(`${upper} ${path} → ${resp.status} ${resp.statusText}: ${text}`);
+        }
+
+        if (opts.parse === false) {
+          process.stdout.write(text + '\n');
+        } else {
+          try {
+            out(JSON.parse(text));
+          } catch {
+            process.stdout.write(text + '\n');
+          }
+        }
+      },
+    );
+}