@oppira/cli 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# Oppira CLI (`oppira`)
+
+Terminal control for Oppira — competitor intelligence, playbook, studio, and ops —
+in one command. Dependency-free Node ESM (Node ≥ 20): runs with just `node`.
+
+## Two execution modes
+
+| Mode | How | Serves | Auth |
+|------|-----|--------|------|
+| **Remote** (default) | HTTP client against the deployed API | customers, agents, CI | JWT login, or durable `ca_` API key |
+| **Local / ops** | Imports the backend engines + Mongo directly | the team | backend `.env` (MONGO_URI + secrets) |
+
+Local mode reaches the **cron-only generators** (insights / alerts / battlecard) and
+the **intelligent scraper** without needing new HTTP endpoints — it mirrors the
+existing one-off scripts in `../scripts` (dotenv + `mongoose.connect` + engine call).
+It only works from a repo checkout with the backend secrets present.
+
+## Install
+
+**For end users (published package):**
+
+```bash
+npm install -g @oppira/cli
+oppira --help
+```
+
+**From the repo (team / ops mode):**
+
+```bash
+cd cli && npm link      # then `oppira` is on your PATH
+# or run directly:
+node cli/bin/oppira.js --help
+```
+
+Only the repo checkout can run the local/ops commands (they need the backend
+`.env` + `node_modules`). The published package runs the **remote** commands.
+
+## First run
+
+```bash
+oppira config set-url https://api.oppira.com     # or leave default http://localhost:3008
+oppira auth login --email you@co.com             # stores a JWT session (~/.oppira)
+oppira comp list
+```
+
+## Authentication: session vs. API key
+
+Two ways to authenticate — pick one per profile:
+
+1. **Login session (works everywhere, default):**
+   ```bash
+   oppira auth login --email you@co.com
+   ```
+   Stores a JWT + refresh token; auto-refreshes. Best for interactive use.
+
+2. **API key (durable — best for CI / agents / automation):**
+   Generate the key in the **Oppira web app**, then paste it into the CLI:
+   ```bash
+   oppira auth key set ca_xxxxxxxx      # or: oppira auth key generate
+   ```
+   > A `ca_` key unlocks the read-only `/mcp` analytics out of the box. To use it
+   > for the **full REST command set**, the server must have
+   > `OPPIRA_CLI_APIKEY_REST=true`. Until that's enabled, use `oppira auth login`
+   > for REST commands.
+
+Config lives in `~/.oppira/config.json`; credentials (tokens, key) in
+`~/.oppira/credentials.json` (chmod 600). Multiple profiles are supported
+(`oppira config use <name>`, `--profile <name>`, or `OPPIRA_PROFILE`).
+
+## Commands
+
+```
+auth        login | logout | whoami | key generate|revoke
+config      show | list | set-url | set-output | use
+comp        list | show | add | track | toggle-tracking | insights | alerts | rm
+discover    profiles | job | suggestions | dismiss
+scrape      run (intelligent, local) | raw <platform> --url
+insights    list | summary | generate*        (*local/ops force-run)
+alerts      list | run*
+battlecard  show | history | regen*
+playbook    show | bootstrap | refresh-section | refresh-cluster
+studio      posts | publish | calendars | calendar-generate | comments | draft-reply
+artifact    get | export
+ask         "<question>"                       (streams the unified agent reply)
+admin       stats | ai-usage | errors | users* | set-plan*
+```
+
+Global flags: `--json` (machine output for scripts/agents), `--local`,
+`--profile <name>`, `--help`, `--version`. Every command exits non-zero on failure.
+
+### Examples
+
+```bash
+oppira ask "compare Acme and Globex activity this month"
+oppira ask "summarize my playbook" --json | jq -r .text
+oppira scrape run Acme --platforms fb,ig            # ops, local mode
+oppira insights generate --email client@co.com      # force cron-only generator
+oppira battlecard regen Globex
+oppira admin errors --limit 20
+oppira admin ai-usage --by-plan
+```
+
+## Server-side: enable API-key REST access (opt-in)
+
+Granting a `ca_` key full REST authority (so users/CI can drive the CLI with just
+an API key instead of a 15-min JWT) is a deliberate security decision and is **off
+by default**. To turn on the "generate a key in the web app → use the CLI" flow,
+set on the server:
+
+```
+OPPIRA_CLI_APIKEY_REST=true
+```
+
+Until then, REST commands authenticate with the JWT session from `oppira auth login`.
+
+## Publishing (maintainers)
+
+The package is publish-ready (`publishConfig.access = public`, `files` whitelist).
+
+```bash
+cd cli
+npm version patch            # or minor/major — bump the version
+npm publish                  # publishes @oppira/cli to npm
+```
+
+Prerequisites & notes:
+- You must own/belong to the **`@oppira`** npm org for the scoped name. If you don't,
+  rename `name` in package.json to an unscoped `oppira-cli` (the `oppira` command name
+  is unchanged) and drop `publishConfig`.
+- `npm login` first; the publish is public.
+- Only `bin/`, `src/`, `README.md` ship (the `files` field) — no repo internals.
+- End users then: `npm install -g @oppira/cli`.
+
+## Status (phased build)
+
+- **Working now:** auth/config, competitors (+ analytics: timeline/compare/top-posts/tone in
+  local mode), discover, playbook, insights/alerts/battlecard reads, `ask` (SSE), artifact
+  get/export, admin (reads + user mgmt + `script` runner folding `../scripts`), studio
+  (posts/calendars/comments/templates/formats/settings/channels/assets/policy + actions),
+  local/ops force-generators + intelligent scrape.
+- **Remote force-generate:** `insights generate`, `alerts run`, `battlecard regen` now hit
+  owner-scoped REST endpoints by default (added to the backend); pass `--local` to run the
+  engine directly instead.
+- **Follow-up (still open):** MCP-backed analytics over HTTP (so timeline/compare/top-N work
+  remotely, not just local), deeper Studio (image-layer editing, ads), and per-endpoint
+  rate-limiting on the force-generate routes.
+```

package/bin/oppira.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Oppira CLI entrypoint. Thin shim — all logic lives in src/ so the package
+// stays testable as a library too (see package.json "exports").
+import { main } from '../src/index.js';
+
+main(process.argv.slice(2)).catch((err) => {
+  // Last-resort handler: src/index.js already renders known errors nicely and
+  // sets process.exitCode. Anything reaching here is unexpected.
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@oppira/cli",
+  "version": "0.1.0",
+  "description": "Oppira CLI — terminal control for the adaptive marketing system (competitor intelligence, playbook, studio, ops).",
+  "type": "module",
+  "bin": {
+    "oppira": "bin/oppira.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/oppira.js",
+    "prepublishOnly": "node --check bin/oppira.js"
+  },
+  "keywords": [
+    "oppira",
+    "cli",
+    "competitor-analysis",
+    "marketing",
+    "competitive-intelligence"
+  ],
+  "homepage": "https://oppira.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Oppira",
+  "license": "UNLICENSED"
+}

package/src/commands/admin.js

@@ -0,0 +1,174 @@
+// admin: ops read surface (stats / AI usage / generation errors) over the
+// admin REST endpoints, plus local user management and a runner that folds the
+// existing ../scripts one-offs under one entry point. Consolidates what used to
+// be ad-hoc scripts + manual mongosh.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { apiRequest } from '../http.js';
+import { withDb, loadModels, findUserOrThrow, backendDir } from '../local.js';
+import { out, table, kv, info } from '../output.js';
+
+const SCRIPTS_DIR = path.join(backendDir, 'scripts');
+
+function listScripts() {
+  try {
+    return fs.readdirSync(SCRIPTS_DIR).filter((f) => f.endsWith('.js') || f.endsWith('.mjs')).sort();
+  } catch { return []; }
+}
+
+// Spawn `node scripts/<file>` from the backend root (scripts load their own
+// dotenv). Resolves with the child exit code.
+function runScript(file, args) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [path.join(SCRIPTS_DIR, file), ...args], {
+      cwd: backendDir,
+      stdio: 'inherit',
+    });
+    child.on('close', (code) => resolve(code ?? 0));
+    child.on('error', (err) => { info(`✗ ${err.message}`); resolve(1); });
+  });
+}
+
+function resolveScriptFile(name) {
+  const files = listScripts();
+  // Accept exact, with-extension, or basename-without-extension.
+  return files.find((f) => f === name || f === `${name}.js` || f === `${name}.mjs` || f.replace(/\.(js|mjs)$/, '') === name);
+}
+
+export default {
+  description: 'Admin / ops — stats, AI usage, generation errors, user management.',
+  commands: {
+    stats: {
+      description: 'Platform stats.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/admin/stats');
+        out(res?.data || res, ctx);
+      },
+    },
+
+    'ai-usage': {
+      description: 'LLM cost / usage summary (add --by-plan to break down by plan).',
+      flags: [{ name: 'by-plan', boolean: true, description: 'Break down by subscription plan' }],
+      async handler(ctx) {
+        const path = ctx.bool('by-plan') ? '/admin/ai-usage/by-plan' : '/admin/ai-usage/summary';
+        const res = await apiRequest(ctx.profileName, 'GET', path);
+        out(res?.data || res, ctx);
+      },
+    },
+
+    errors: {
+      description: 'Recent AI generation errors.',
+      usage: 'admin errors [--limit 50]',
+      flags: [{ name: 'limit', description: 'Max rows' }],
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/admin/generation-errors', {
+          query: { limit: ctx.flag('limit') },
+        });
+        const list = res?.data || res?.errors || res || [];
+        if (ctx.json) { out(list, ctx); return; }
+        const rows = (Array.isArray(list) ? list : []).map((e) => ({
+          when: e.createdAt || e.timestamp || '—',
+          subsystem: e.subsystem || '—',
+          flow: e.flow || '—',
+          user: e.userEmail || '—',
+          reason: e.reason || e.message || '—',
+        }));
+        table(rows, [
+          { key: 'when', label: 'WHEN' }, { key: 'subsystem', label: 'SUBSYSTEM' },
+          { key: 'flow', label: 'FLOW' }, { key: 'user', label: 'USER' },
+          { key: 'reason', label: 'REASON', max: 50 },
+        ], ctx);
+      },
+    },
+
+    users: {
+      description: 'List users (local/ops). Filter with --email substring.',
+      usage: 'admin users [--email foo]',
+      flags: [{ name: 'email', description: 'Filter by email substring' }],
+      async handler(ctx) {
+        const rows = await withDb(async () => {
+          const { User } = await loadModels();
+          const q = ctx.flag('email') ? { email: new RegExp(String(ctx.flag('email')), 'i') } : {};
+          const users = await User.find(q).select('email subscriptionPlan enabled emailVerified createdAt stripeCustomerId').limit(200);
+          return users.map((u) => ({
+            email: u.email,
+            plan: u.subscriptionPlan || 'free',
+            enabled: u.enabled ? 'yes' : 'no',
+            verified: u.emailVerified ? 'yes' : 'no',
+            stripe: u.stripeCustomerId ? 'yes' : 'no',
+          }));
+        });
+        table(rows, [
+          { key: 'email', label: 'EMAIL' }, { key: 'plan', label: 'PLAN' },
+          { key: 'enabled', label: 'ENABLED' }, { key: 'verified', label: 'VERIFIED' },
+          { key: 'stripe', label: 'STRIPE' },
+        ], ctx);
+      },
+    },
+
+    'set-plan': {
+      description: 'Set a user\'s plan (local/ops). Refuses Stripe-managed accounts unless --force.',
+      usage: 'admin set-plan <email> <plan> [--force]',
+      flags: [{ name: 'force', boolean: true, description: 'Override the Stripe-managed guard' }],
+      async handler(ctx) {
+        const email = ctx.arg(0);
+        const plan = ctx.arg(1);
+        const allowed = ['free', 'basic', 'pro', 'data', 'admin'];
+        if (!email || !allowed.includes(plan)) throw new Error(`Usage: oppira admin set-plan <email> <${allowed.join('|')}>`);
+        const result = await withDb(async () => {
+          const user = await findUserOrThrow(email);
+          if (user.stripeCustomerId && !ctx.bool('force')) {
+            throw new Error(`${email} is Stripe-managed (stripeCustomerId set). Changing the plan here will drift from billing. Re-run with --force if you really mean it.`);
+          }
+          const prev = user.subscriptionPlan;
+          user.subscriptionPlan = plan;
+          await user.save();
+          return { email, from: prev, to: plan };
+        });
+        if (ctx.json) { out({ success: true, ...result }, ctx); return; }
+        info(`✓ ${result.email}: ${result.from} → ${result.to}`);
+      },
+    },
+
+    script: {
+      description: 'Run a backend ops script (folds ../scripts). No name → list them.',
+      usage: 'admin script <name> [-- <script args>]',
+      async handler(ctx) {
+        const name = ctx.arg(0);
+        const scripts = listScripts();
+        if (!name) {
+          if (ctx.json) { out(scripts, ctx); return; }
+          info('Available ops scripts (run: oppira admin script <name> -- <args>):');
+          for (const s of scripts) info(`  ${s.replace(/\.(js|mjs)$/, '')}`);
+          return;
+        }
+        const file = resolveScriptFile(name);
+        if (!file) throw new Error(`Unknown script "${name}". One of: ${scripts.map((s) => s.replace(/\.(js|mjs)$/, '')).join(', ')}`);
+        // positionals[0] is the name; everything after (incl. what followed `--`) are script args.
+        const scriptArgs = ctx.positionals.slice(1);
+        info(`▶ node scripts/${file} ${scriptArgs.join(' ')}`.trim());
+        const code = await runScript(file, scriptArgs);
+        process.exitCode = code;
+      },
+    },
+
+    'backfill-digests': {
+      description: 'Backfill CompetitorMonthlyDigest records (shortcut for the backfill script).',
+      usage: 'admin backfill-digests [--competitor <id>] [--force]',
+      flags: [
+        { name: 'competitor', description: 'Limit to one competitor id' },
+        { name: 'force', boolean: true, description: 'Ignore the checkpoint, redo everyone' },
+      ],
+      async handler(ctx) {
+        const file = resolveScriptFile('backfillCompetitorDigests');
+        if (!file) throw new Error('backfillCompetitorDigests script not found in ../scripts.');
+        const args = [];
+        if (ctx.flag('competitor')) args.push(`--competitorId=${ctx.flag('competitor')}`);
+        if (ctx.bool('force')) args.push('--force');
+        const code = await runScript(file, args);
+        process.exitCode = code;
+      },
+    },
+  },
+};

package/src/commands/alerts.js

@@ -0,0 +1,64 @@
+// alerts: read (REST) + force-generate (local engine, cron-only otherwise).
+import { apiRequest } from '../http.js';
+import { getCredentials } from '../config.js';
+import { withDb, findUserOrThrow, backendImport } from '../local.js';
+import { out, table, info } from '../output.js';
+
+function opsEmail(ctx) {
+  const email = ctx.flag('email') || getCredentials(ctx.profileName).email;
+  if (!email) throw new Error('Provide --email (or log in) to select the target user.');
+  return email;
+}
+
+export default {
+  description: 'Alerts — list activity alerts and force-generate (ops).',
+  commands: {
+    list: {
+      description: 'List competitor-activity alerts.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/users/alerts');
+        const alerts = res?.data || res?.alerts || res || [];
+        if (ctx.json) { out(alerts, ctx); return; }
+        const rows = (Array.isArray(alerts) ? alerts : []).map((a) => ({
+          severity: a.severity || a.priority || '—',
+          type: a.type || a.alertType || '—',
+          competitor: a.competitorName || a.competitor || '—',
+          message: a.message || a.title || '—',
+          read: a.read || a.isRead ? 'yes' : 'no',
+        }));
+        table(rows, [
+          { key: 'severity', label: 'SEV' }, { key: 'type', label: 'TYPE' },
+          { key: 'competitor', label: 'COMPETITOR' }, { key: 'message', label: 'MESSAGE', max: 55 },
+          { key: 'read', label: 'READ' },
+        ], ctx);
+      },
+    },
+
+    run: {
+      description: 'Force-generate alerts now (remote by default; --local runs the engine directly).',
+      usage: 'alerts run [--local] [--email you@co.com]',
+      flags: [
+        { name: 'local', boolean: true, description: 'Run the engine directly (ops; needs repo + .env)' },
+        { name: 'email', description: 'Target user in --local mode (defaults to logged-in profile)' },
+      ],
+      async handler(ctx) {
+        if (!ctx.useLocal) {
+          const res = await apiRequest(ctx.profileName, 'POST', '/alerts/generate', { body: {} });
+          if (ctx.json) { out(res, ctx); return; }
+          info('✓ Alert generation triggered.');
+          if (res?.result) out(res.result, ctx);
+          return;
+        }
+        const email = opsEmail(ctx);
+        const result = await withDb(async () => {
+          const user = await findUserOrThrow(email);
+          const { generateAlertsForUser } = await backendImport('utils/alertGenerator.js');
+          return generateAlertsForUser(user);
+        });
+        if (ctx.json) { out({ success: true, email, result }, ctx); return; }
+        info(`✓ Alert generation run for ${email} (local).`);
+        if (result) out(result, ctx);
+      },
+    },
+  },
+};

package/src/commands/artifact.js

@@ -0,0 +1,50 @@
+// artifact: fetch a generated artifact (report/deck/diagram) and export it to
+// a file. Export can be binary (pdf/pptx), so it bypasses the JSON client.
+import fs from 'node:fs';
+import { apiRequest } from '../http.js';
+import { getProfile, getCredentials } from '../config.js';
+import { out, info } from '../output.js';
+
+function joinUrl(base, pathname) { return `${base.replace(/\/$/, '')}/${pathname.replace(/^\//, '')}`; }
+
+export default {
+  description: 'Artifacts — fetch and export generated reports/decks/diagrams.',
+  commands: {
+    get: {
+      description: 'Fetch an artifact by id.',
+      usage: 'artifact get <id>',
+      async handler(ctx) {
+        const id = ctx.arg(0);
+        if (!id) throw new Error('Usage: oppira artifact get <id>');
+        const res = await apiRequest(ctx.profileName, 'GET', `/assistant/artifacts/${id}`);
+        out(res, ctx);
+      },
+    },
+
+    export: {
+      description: 'Export an artifact to a file (md/html/pdf/pptx).',
+      usage: 'artifact export <id> --format md [--out file]',
+      flags: [
+        { name: 'format', description: 'Export format (md, html, pdf, pptx, …)' },
+        { name: 'out', description: 'Output file path (default: <id>.<format>)' },
+      ],
+      async handler(ctx) {
+        const id = ctx.arg(0);
+        const format = ctx.flag('format') || 'md';
+        if (!id) throw new Error('Usage: oppira artifact export <id> --format md [--out file]');
+        const profile = getProfile(ctx.profileName);
+        const creds = getCredentials(profile.name);
+        const auth = creds.accessToken ? `Bearer ${creds.accessToken}` : (creds.apiKey ? `Bearer ${creds.apiKey}` : null);
+        const res = await fetch(joinUrl(profile.apiUrl, `/assistant/artifacts/${id}/export/${format}`), {
+          headers: auth ? { Authorization: auth } : {},
+        });
+        if (!res.ok) throw new Error(`Export failed (${res.status})`);
+        const buf = Buffer.from(await res.arrayBuffer());
+        const outPath = ctx.flag('out') || `${id}.${format}`;
+        fs.writeFileSync(outPath, buf);
+        if (ctx.json) { out({ success: true, file: outPath, bytes: buf.length }, ctx); return; }
+        info(`✓ Exported ${buf.length} bytes → ${outPath}`);
+      },
+    },
+  },
+};

package/src/commands/ask.js

@@ -0,0 +1,53 @@
+// ask: one-shot question to the unified agent (/agent/chat, SSE). The
+// orchestrator picks intel / strategist / planner; we stream the reply to
+// stdout. Reads the message from args or stdin (so you can pipe into it).
+import { streamChat } from '../sse.js';
+import { out, info } from '../output.js';
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8').trim();
+}
+
+export const askCommand = {
+  description: 'Ask the Oppira agent a question (streams the reply). Reads from args or stdin.',
+  usage: 'ask "compare Acme and Globex activity" [--conversation <id>] [--json]',
+  flags: [
+    { name: 'conversation', description: 'Continue an existing conversation by id' },
+    { name: 'json', boolean: true, description: 'Emit a single JSON object instead of streaming text' },
+  ],
+  async handler(ctx) {
+    let message = ctx.positionals.join(' ').trim();
+    if (!message) message = await readStdin();
+    if (!message) throw new Error('Nothing to ask. Provide a message or pipe text in.');
+
+    const conversationId = ctx.flag('conversation');
+    let agent = null;
+    let convId = null;
+    let text = '';
+
+    await streamChat(ctx.profileName, { message, conversationId }, (ev) => {
+      switch (ev.type) {
+        case 'conversation-id': convId = ev.id; break;
+        case 'agent':
+          agent = ev.agent;
+          if (!ctx.json) info(`[${ev.agent}]`);
+          break;
+        case 'text-delta':
+          text += ev.delta || '';
+          if (!ctx.json) process.stdout.write(ev.delta || '');
+          break;
+        default: break; // navigate & others: ignore for CLI
+      }
+    });
+
+    if (ctx.json) {
+      out({ conversationId: convId, agent, text }, ctx);
+    } else {
+      process.stdout.write('\n');
+      if (convId) info(`\n(conversation: ${convId} — continue with: oppira ask "..." --conversation ${convId})`);
+    }
+  },
+};

package/src/commands/auth.js

@@ -0,0 +1,134 @@
+// auth: login (JWT session), logout, whoami, and durable API-key management.
+import readline from 'node:readline';
+import { login, apiRequest, ApiError } from '../http.js';
+import { getProfile, getCredentials, setCredentials, clearCredentials } from '../config.js';
+import { out, kv, info } from '../output.js';
+
+function question(query, { hidden } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    if (hidden) {
+      rl._writeToOutput = (str) => {
+        if (str.includes(query)) rl.output.write(query);
+        else rl.output.write('');
+      };
+    }
+    rl.question(query, (answer) => {
+      rl.close();
+      if (hidden) rl.output.write('\n');
+      resolve(answer.trim());
+    });
+  });
+}
+
+export default {
+  description: 'Authentication — login, API keys, session info.',
+  commands: {
+    login: {
+      description: 'Log in with email + password (stores a JWT session for this profile).',
+      usage: 'auth login [--email you@co.com] [--password ***]',
+      flags: [
+        { name: 'email', description: 'Account email (prompted if omitted)' },
+        { name: 'password', description: 'Account password (prompted, hidden, if omitted)' },
+      ],
+      async handler(ctx) {
+        const profile = getProfile(ctx.profileName);
+        const email = ctx.flag('email') || await question('Email: ');
+        const password = ctx.flag('password') || await question('Password: ', { hidden: true });
+        const { user } = await login(profile.name, email, password);
+        const plan = user?.subscriptionPlan || 'free';
+        if (ctx.json) { out({ success: true, profile: profile.name, email: user?.email, plan }, ctx); return; }
+        info(`✓ Logged in as ${user?.email} (plan: ${plan}) on profile "${profile.name}" → ${profile.apiUrl}`);
+      },
+    },
+
+    logout: {
+      description: 'Clear stored credentials for the current profile.',
+      async handler(ctx) {
+        clearCredentials(ctx.profileName);
+        if (ctx.json) { out({ success: true, profile: ctx.profileName }, ctx); return; }
+        info(`✓ Logged out of profile "${ctx.profileName}".`);
+      },
+    },
+
+    whoami: {
+      description: 'Show the current account / session.',
+      async handler(ctx) {
+        const profile = getProfile(ctx.profileName);
+        const creds = getCredentials(profile.name);
+        if (!creds.accessToken && !creds.apiKey) {
+          info(`Not logged in on profile "${profile.name}". Run: oppira auth login`);
+          process.exitCode = 1;
+          return;
+        }
+        try {
+          const res = await apiRequest(profile.name, 'POST', '/users/validate-token', { body: {} });
+          const user = res?.user || res;
+          kv({
+            profile: profile.name,
+            apiUrl: profile.apiUrl,
+            email: user?.email || creds.email,
+            plan: user?.subscriptionPlan,
+            hasApiKey: Boolean(creds.apiKey),
+          }, ctx);
+        } catch (err) {
+          // Token check failed but we have stored creds — show what we know.
+          if (err instanceof ApiError) info(`(session check failed: ${err.message})`);
+          kv({ profile: profile.name, apiUrl: profile.apiUrl, email: creds.email, hasApiKey: Boolean(creds.apiKey) }, ctx);
+        }
+      },
+    },
+
+    key: {
+      description: 'Manage the durable API key: generate | set <key> | show | revoke.',
+      usage: 'auth key <generate|set <ca_...>|show|revoke>',
+      async handler(ctx) {
+        const action = ctx.arg(0);
+        const profile = getProfile(ctx.profileName);
+
+        if (action === 'generate') {
+          const res = await apiRequest(profile.name, 'POST', '/users/generate-api-key', { body: {} });
+          setCredentials(profile.name, { apiKey: res.apiKey });
+          if (ctx.json) { out({ success: true, apiKey: res.apiKey }, ctx); return; }
+          info('✓ API key generated and stored for this profile.');
+          info(`  ${res.apiKey}`);
+          return;
+        }
+
+        // Store a key generated elsewhere (e.g. on the Oppira web app). This is
+        // the usual customer flow: create the key in the UI, paste it here.
+        if (action === 'set') {
+          const key = ctx.arg(1) || ctx.flag('key');
+          if (!key || !String(key).startsWith('ca_')) {
+            throw new Error('Provide the key: oppira auth key set ca_xxxxx');
+          }
+          setCredentials(profile.name, { apiKey: String(key) });
+          if (ctx.json) { out({ success: true }, ctx); return; }
+          info(`✓ API key stored for profile "${profile.name}".`);
+          info('  Note: REST commands accept this key only if the server has OPPIRA_CLI_APIKEY_REST=true;');
+          info('  otherwise the key is used for MCP/analytics and you log in with "oppira auth login" for REST.');
+          return;
+        }
+
+        if (action === 'show') {
+          const creds = getCredentials(profile.name);
+          if (!creds.apiKey) { info('No API key stored for this profile.'); process.exitCode = 1; return; }
+          const masked = `${creds.apiKey.slice(0, 6)}…${creds.apiKey.slice(-4)}`;
+          if (ctx.json) { out({ apiKey: masked }, ctx); return; }
+          info(`API key (profile "${profile.name}"): ${masked}`);
+          return;
+        }
+
+        if (action === 'revoke') {
+          await apiRequest(profile.name, 'DELETE', '/users/revoke-api-key', {});
+          setCredentials(profile.name, { apiKey: undefined });
+          if (ctx.json) { out({ success: true }, ctx); return; }
+          info('✓ API key revoked.');
+          return;
+        }
+
+        throw new Error('Usage: oppira auth key <generate|set <ca_...>|show|revoke>');
+      },
+    },
+  },
+};