@empirical-gauzza/cli 1.0.21 → 1.0.23

package/README.md

@@ -1,63 +1,63 @@
-# @empirical-gauzza/cli
-
-Command-line installer and local MCP wiring helper for [Empirical](https://empirical.gauzza.com) — portable memory infrastructure for AI agents, assistants, and coding tools.
-
-Full documentation: **[empirical.gauzza.com/docs/cli-details](https://empirical.gauzza.com/docs/cli-details)**
-
-## Install
-
-```bash
-npm install -g @empirical-gauzza/cli
-```
-
-## Quick start
-
-```bash
-empirical install       # interactive setup for Claude Code, Codex, or Copilot CLI
-empirical auth login    # browser-based OAuth login
-empirical doctor        # verify token, API connectivity, and workspace status
-```
-
-Full walkthrough: [empirical.gauzza.com/docs/install](https://empirical.gauzza.com/docs/install)
-
-## What it does
-
-- Installs and configures the Empirical MCP plugin for supported coding agents (Claude Code, Codex CLI, Copilot CLI)
-- Manages OAuth login, including headless/CI bootstrap and Docker token flows
-- Reads, writes, and maintains memories from the command line
-- Manages Skills Kits — create, sync, and push authored Skills across machines
-- Manages workspaces, invites, and registered devices
-- Exposes agent-readable docs and a connectivity `doctor` check
-
-## Commands
-
-| Command | Docs |
-| --- | --- |
-| `empirical install` | [/docs/install](https://empirical.gauzza.com/docs/install#connect) |
-| `empirical plugin install / check` | [/docs/cli-plugins](https://empirical.gauzza.com/docs/cli-plugins) |
-| `empirical auth login / logout` | [/docs/cli-auth](https://empirical.gauzza.com/docs/cli-auth) |
-| `empirical oauth bootstrap / refresh` | [/docs/cli-oauth](https://empirical.gauzza.com/docs/cli-oauth) |
-| `empirical policy show / set` | [/docs/cli-policy](https://empirical.gauzza.com/docs/cli-policy) |
-| `empirical memory query / record / update / delete / export ...` | [/docs/cli-memory](https://empirical.gauzza.com/docs/cli-memory) |
-| `empirical workspace list / create / invite ...` | [/docs/cli-workspaces](https://empirical.gauzza.com/docs/cli-workspaces) |
-| `empirical kit create / sync / use ...` | [/docs/cli-kit](https://empirical.gauzza.com/docs/cli-kit) |
-| `empirical skill push / history / rollback` | [/docs/cli-skill](https://empirical.gauzza.com/docs/cli-skill) |
-| `empirical device list / show` | [/docs/cli-devices](https://empirical.gauzza.com/docs/cli-devices) |
-| `empirical doc [topic]` | [/docs/cli-doc-command](https://empirical.gauzza.com/docs/cli-doc-command) |
-| `empirical doctor` | [/docs/cli-doctor](https://empirical.gauzza.com/docs/cli-doctor) |
-
-Run `empirical --help` at any time for the full, current command list, or `empirical doc` for agent-readable topic docs.
-
-## Security model
-
-API keys and OAuth tokens are stored locally and are never printed in full after initial issuance. See [empirical.gauzza.com/docs/security-model](https://empirical.gauzza.com/docs/security-model) for details on credential handling and headless/CI usage.
-
-## Links
-
-- [Documentation](https://empirical.gauzza.com/docs/install)
-- [Homepage](https://empirical.gauzza.com)
-- [Support](https://empirical.gauzza.com/support/)
-
-## License
-
-MIT
+# @empirical-gauzza/cli
+
+Command-line installer and local MCP wiring helper for [Empirical](https://empirical.gauzza.com) — portable memory infrastructure for AI agents, assistants, and coding tools.
+
+Full documentation: **[empirical.gauzza.com/docs/cli-details](https://empirical.gauzza.com/docs/cli-details)**
+
+## Install
+
+```bash
+npm install -g @empirical-gauzza/cli
+```
+
+## Quick start
+
+```bash
+empirical install       # interactive setup for Claude Code, Codex, or Copilot CLI
+empirical auth login    # browser-based OAuth login
+empirical doctor        # verify token, API connectivity, and workspace status
+```
+
+Full walkthrough: [empirical.gauzza.com/docs/install](https://empirical.gauzza.com/docs/install)
+
+## What it does
+
+- Installs and configures the Empirical MCP plugin for supported coding agents (Claude Code, Codex CLI, Copilot CLI)
+- Manages OAuth login, including headless/CI bootstrap and Docker token flows
+- Reads, writes, and maintains memories from the command line
+- Manages Skills Kits — create, sync, and push authored Skills across machines
+- Manages workspaces, invites, and registered devices
+- Exposes agent-readable docs and a connectivity `doctor` check
+
+## Commands
+
+| Command | Docs |
+| --- | --- |
+| `empirical install` | [/docs/install](https://empirical.gauzza.com/docs/install#connect) |
+| `empirical plugin install / check` | [/docs/cli-plugins](https://empirical.gauzza.com/docs/cli-plugins) |
+| `empirical auth login / logout` | [/docs/cli-auth](https://empirical.gauzza.com/docs/cli-auth) |
+| `empirical oauth bootstrap / refresh` | [/docs/cli-oauth](https://empirical.gauzza.com/docs/cli-oauth) |
+| `empirical policy show / set` | [/docs/cli-policy](https://empirical.gauzza.com/docs/cli-policy) |
+| `empirical memory query / record / update / delete / export ...` | [/docs/cli-memory](https://empirical.gauzza.com/docs/cli-memory) |
+| `empirical workspace list / create / invite ...` | [/docs/cli-workspaces](https://empirical.gauzza.com/docs/cli-workspaces) |
+| `empirical kit create / sync / use ...` | [/docs/cli-kit](https://empirical.gauzza.com/docs/cli-kit) |
+| `empirical skill push / history / rollback` | [/docs/cli-skill](https://empirical.gauzza.com/docs/cli-skill) |
+| `empirical device list / show` | [/docs/cli-devices](https://empirical.gauzza.com/docs/cli-devices) |
+| `empirical doc [topic]` | [/docs/cli-doc-command](https://empirical.gauzza.com/docs/cli-doc-command) |
+| `empirical doctor` | [/docs/cli-doctor](https://empirical.gauzza.com/docs/cli-doctor) |
+
+Run `empirical --help` at any time for the full, current command list, or `empirical doc` for agent-readable topic docs.
+
+## Security model
+
+API keys and OAuth tokens are stored locally and are never printed in full after initial issuance. See [empirical.gauzza.com/docs/security-model](https://empirical.gauzza.com/docs/security-model) for details on credential handling and headless/CI usage.
+
+## Links
+
+- [Documentation](https://empirical.gauzza.com/docs/install)
+- [Homepage](https://empirical.gauzza.com)
+- [Support](https://empirical.gauzza.com/support/)
+
+## License
+
+MIT

package/bin/empirical.js

@@ -23,6 +23,8 @@ const { runDoc } = require('../lib/doc');
 const { showVersion } = require('../lib/help');
 const { isPluginCommand, runPluginCommand } = require('../lib/pluginCommands');
 const { runPolicyCommand } = require('../lib/policyCommands');
+const { runSetupCommand } = require('../lib/setupCommands');
+const { runBlueprintCommand } = require('../lib/blueprintCommands');
 const { checkNativePluginUpdates } = require('../lib/pluginUpdateCheck');
 
 async function main() {
@@ -104,6 +106,16 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'setup') {
+    await runSetupCommand(args.slice(1));
+    return;
+  }
+
+  if (args[0] === 'blueprint') {
+    await runBlueprintCommand(args.slice(1));
+    return;
+  }
+
   if (isAuthCommand(args)) {
     await runAuthCommand(args);
     return;

package/lib/auth.js

@@ -401,13 +401,79 @@ async function runAuthCommand(args) {
     return;
   }
 
+  // `logout` used to only delete the local session file, which left every refresh token on
+  // the account still redeemable forever. It now revokes server-side first, so logging out
+  // actually ends the session. --local-only keeps the old behavior for the case where you
+  // just want this machine to forget its credentials without signing out your other clients.
   if (action === 'logout') {
+    const localOnly = args.includes('--local-only');
+    if (!localOnly) {
+      const baseUrl = resolveApiBaseUrl();
+      const token = resolveAccessToken();
+      if (token) {
+        try {
+          const res = await revokeRefreshTokens(baseUrl, token, { clientId: parseOption(args, '--client-id') });
+          const data = (res && res.data) ? res.data : res;
+          log(`Revoked ${data.revoked} refresh token(s) server-side; ${data.remaining} remaining.`);
+        } catch (error) {
+          warn(`Server-side revoke failed (${error.message}). Clearing the local session anyway; run 'empirical auth logout' again once you can reach the API.`);
+          process.exitCode = 1;
+        }
+      } else {
+        warn('No stored credential found, so nothing could be revoked server-side. Clearing local session only.');
+      }
+    }
     clearOAuthSession();
-    log('Empirical OAuth session cleared.');
+    log(localOnly ? 'Local Empirical session cleared (server-side tokens left intact).' : 'Empirical session cleared.');
+    return;
+  }
+
+  // Rotate: mint a replacement API key. `--replace-all` uses the destructive server-side
+  // rotate that wipes every existing key; the default appends a new key and leaves the
+  // others working, so you can cut over before revoking the old one.
+  if (action === 'rotate-key') {
+    const baseUrl = resolveApiBaseUrl();
+    const token = requireAccessToken();
+    const result = await fetchSelfServiceCredentials(baseUrl, token, {
+      rotate: args.includes('--replace-all'),
+      label: parseOption(args, '--label')
+    });
+    const data = (result && result.data) ? result.data : result;
+    if (!data || !data.apiKey) {
+      warn('The server did not return a new key. Nothing was changed.');
+      process.exitCode = 1;
+      return;
+    }
+    log(JSON.stringify({ clientId: data.clientId || data.userId, apiKey: data.apiKey, keyId: data.keyId || null }, null, 2));
+    log('\nStore this now: the key is shown once and only its hash is kept.');
+    return;
+  }
+
+  if (action === 'list-keys') {
+    const baseUrl = resolveApiBaseUrl();
+    const token = requireAccessToken();
+    const result = await fetchSelfServiceCredentialStatus(baseUrl, token);
+    log(JSON.stringify((result && result.data) ? result.data : result, null, 2));
     return;
   }
 
-  warn('Usage: empirical auth <login|logout|status> (or: empirical whoami)');
+  if (action === 'revoke-key') {
+    const baseUrl = resolveApiBaseUrl();
+    const token = requireAccessToken();
+    const id = parseOption(args, '--key-id');
+    const all = args.includes('--all');
+    if (!id && !all) {
+      warn('Usage: empirical auth revoke-key (--key-id <id> | --all)   [list ids with: empirical auth list-keys]');
+      process.exitCode = 1;
+      return;
+    }
+    const result = await revokeSelfServiceCredential(baseUrl, token, { id: all ? undefined : id });
+    log(JSON.stringify((result && result.data) ? result.data : result, null, 2));
+    log(all ? '\nEvery API key on this account is revoked.' : `\nKey ${id} revoked.`);
+    return;
+  }
+
+  warn('Usage: empirical auth <login|logout|status|rotate-key|list-keys|revoke-key> (or: empirical whoami)');
   process.exitCode = 1;
 }
 
@@ -601,6 +667,19 @@ async function fetchSelfServiceCredentialStatus(baseUrl, accessToken) {
   return httpJson(url, 'GET', undefined, { Authorization: `Bearer ${accessToken}` });
 }
 
+// Revoke one API key by id, or every key when `id` is omitted.
+async function revokeSelfServiceCredential(baseUrl, accessToken, { id } = {}) {
+  const url = new URL('/api/v1/users/me/credentials', baseUrl).toString();
+  return httpJson(url, 'DELETE', id ? { id } : {}, { Authorization: `Bearer ${accessToken}` });
+}
+
+// Revoke OAuth refresh tokens: one client's when `clientId` is given, otherwise all of them.
+// This is what makes `empirical auth logout` end the session on the server and not just on disk.
+async function revokeRefreshTokens(baseUrl, accessToken, { clientId } = {}) {
+  const url = new URL('/api/v1/users/me/refresh-tokens', baseUrl).toString();
+  return httpJson(url, 'DELETE', clientId ? { clientId } : {}, { Authorization: `Bearer ${accessToken}` });
+}
+
 async function selfProvisionHeadlessCredentials({ baseUrl, allowBrowserLogin = true } = {}) {
   let bearer = resolveAccessToken();
 
@@ -881,6 +960,8 @@ module.exports = {
   ensureOAuthClient,
   fetchSelfServiceCredentials,
   fetchSelfServiceCredentialStatus,
+  revokeSelfServiceCredential,
+  revokeRefreshTokens,
   selfProvisionHeadlessCredentials,
   runHeadlessBootstrap,
   runHeadlessRefresh

package/lib/blueprintCommands.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const { httpJson, printApiError } = require('./http');
+const { parseOption } = require('./env');
+const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { warn, log } = require('./ui');
+
+function apiUrl(pathSuffix) {
+  return new URL(`/api/v1/blueprints${pathSuffix}`, resolveApiBaseUrl()).toString();
+}
+
+async function callApi(method, pathSuffix, body) {
+  const accessToken = requireAccessToken();
+  try {
+    const response = await httpJson(apiUrl(pathSuffix), method, body, buildApiAuthHeaders(accessToken));
+    return response && response.data ? response.data : response;
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
+async function waitForInstall(installId) {
+  for (let i = 0; i < 25; i += 1) {
+    const status = await callApi('GET', `/installs/${installId}`, undefined);
+    if (['succeeded', 'failed', 'rolled_back', 'dead_letter', 'uninstalled'].includes(String(status.jobStatus))) {
+      return status;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 900));
+  }
+  return { installId, jobStatus: 'running' };
+}
+
+async function runList(args) {
+  const category = parseOption(args, '--category', '');
+  const qs = category ? `?category=${encodeURIComponent(category)}` : '';
+  const { items } = await callApi('GET', qs, undefined);
+  log(JSON.stringify(items, null, 2));
+}
+
+async function runShow(args) {
+  const [blueprintId] = args;
+  if (!blueprintId) {
+    warn('Usage: empirical blueprint show <blueprintId>');
+    process.exit(1);
+  }
+  const result = await callApi('GET', `/${blueprintId}`, undefined);
+  log(JSON.stringify(result, null, 2));
+}
+
+async function runClaim(args) {
+  const [blueprintId] = args;
+  if (!blueprintId) {
+    warn('Usage: empirical blueprint claim <blueprintId>');
+    process.exit(1);
+  }
+  const result = await callApi('POST', `/${blueprintId}/claim`, {});
+  log(JSON.stringify(result, null, 2));
+}
+
+async function runInstall(args) {
+  const blueprintId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  if (!blueprintId) {
+    warn('Usage: empirical blueprint install <blueprintId> [--version <v>]');
+    process.exit(1);
+  }
+  const version = parseOption(args, '--version', '');
+
+  const detail = await callApi('GET', `/${blueprintId}`, undefined);
+  if (!detail.owned && detail.priceModel === 'free') {
+    await callApi('POST', `/${blueprintId}/claim`, {});
+  }
+
+  const installResult = await callApi('POST', `/${blueprintId}/install`, version ? { version } : {});
+  const finalStatus = await waitForInstall(installResult.installId);
+  log(JSON.stringify(finalStatus, null, 2));
+}
+
+async function runStatus(args) {
+  const [installId] = args;
+  if (!installId) {
+    warn('Usage: empirical blueprint status <installId>');
+    process.exit(1);
+  }
+  const result = await callApi('GET', `/installs/${installId}`, undefined);
+  log(JSON.stringify(result, null, 2));
+}
+
+async function runInstalled() {
+  const { items } = await callApi('GET', '/installed', undefined);
+  log(JSON.stringify(items, null, 2));
+}
+
+async function runUpdate(args) {
+  const [blueprintId] = args;
+  if (!blueprintId) {
+    warn('Usage: empirical blueprint update <blueprintId>');
+    process.exit(1);
+  }
+  const result = await callApi('POST', `/${blueprintId}/update`, {});
+  log(JSON.stringify(result, null, 2));
+}
+
+async function runUninstall(args) {
+  const [blueprintId, installId] = args;
+  if (!blueprintId || !installId) {
+    warn('Usage: empirical blueprint uninstall <blueprintId> <installId>');
+    process.exit(1);
+  }
+  const result = await callApi('POST', `/${blueprintId}/uninstall`, { installId });
+  log(JSON.stringify(result, null, 2));
+}
+
+async function runBlueprintCommand(args) {
+  const [sub, ...rest] = args;
+  if (sub === 'list') return runList(rest);
+  if (sub === 'show') return runShow(rest);
+  if (sub === 'claim') return runClaim(rest);
+  if (sub === 'install') return runInstall(rest);
+  if (sub === 'status') return runStatus(rest);
+  if (sub === 'installed') return runInstalled();
+  if (sub === 'update') return runUpdate(rest);
+  if (sub === 'uninstall') return runUninstall(rest);
+  warn('Usage: empirical blueprint <list|show|claim|install|status|installed|update|uninstall> ...');
+  process.exit(1);
+}
+
+module.exports = { runBlueprintCommand };

package/lib/constants.js

@@ -60,9 +60,22 @@ Save a new memory.
 
     empirical memory record --category build --summary "Use ESM modules for all new packages" [--tags ts,node] [--node-type observation]
 
+Passing text that contains code (backticks, \${...}, $(...)): do NOT put it in a double-quoted
+\`--summary "..."\` -- the shell substitutes those away before the CLI runs and the write still
+succeeds with the code silently missing. Use one of:
+
+    empirical memory record --category build --summary-file ./note.md --tags ts
+    empirical memory record --category build --summary - --tags ts <<'EOF'
+    Use \`createChat()\`; raw calls leak \${stage} and 400.
+    EOF
+
+(a single-quoted heredoc delimiter, 'EOF', disables substitution). From an MCP-connected agent,
+prefer the record_graph_memory tool, which takes JSON and never touches a shell.
+
 Flags:
 - \`--category\` (required unless --json-file): memory category
-- \`--summary\` (required unless --json-file): memory summary text
+- \`--summary\` (required unless --summary-file/--json-file): memory summary text; \`-\` reads stdin
+- \`--summary-file\`: path to a file whose contents become the summary (safe for code)
 - \`--tags\`: comma-separated tags
 - \`--node-type\`: node type, default \`observation\`
 - \`--json-file\`: path to JSON file with full memory payload
@@ -431,6 +444,33 @@ Opens the browser, completes OAuth with the Empirical account, and saves a CLI s
 \`~/.empirical/oauth-session.json\`. Use this for normal interactive CLI use when you do not
 want to provision a permanent API key.
 
+## Logging out (and actually revoking)
+
+    empirical auth logout                 # revoke refresh tokens server-side, then clear locally
+    empirical auth logout --local-only    # forget this machine only, leave other clients signed in
+    empirical auth logout --client-id <id>  # revoke just one client's refresh tokens
+
+Plain \`logout\` calls \`DELETE /api/v1/users/me/refresh-tokens\`, so the session ends on the
+server and not merely on disk. This matters because refresh tokens are written without an
+expiry: before this existed, a leaked refresh token stayed redeemable forever and no command,
+endpoint or portal screen could revoke it.
+
+## Managing API keys
+
+    empirical auth list-keys                          # ids, labels, created dates
+    empirical auth rotate-key [--label <name>]        # mint an ADDITIONAL key, others keep working
+    empirical auth rotate-key --replace-all           # destructive: wipe every key, mint exactly one
+    empirical auth revoke-key --key-id <id>           # revoke one key
+    empirical auth revoke-key --all                   # revoke every key on the account
+
+Rotating without \`--replace-all\` is the safe cutover: mint the new key, move your integrations
+over, then \`revoke-key --key-id\` the old one. A key is displayed once at mint time; only its
+hash is stored, so there is no way to read it back later.
+
+Minting requires a signed-in session (browser login or a fresh OAuth session), because a
+permanent API key must not be able to mint more credentials. Revoking does not: it only ever
+reduces access, and the CLI needs to be able to revoke with the credential it already holds.
+
 ## Bootstrap command (headless / non-interactive)
 
     empirical oauth bootstrap headless --write-env

package/lib/doc.js

@@ -11,7 +11,7 @@ function runDoc(args) {
     user: 'Get current user identity (MCP: get_user; CLI: doctor --output json)',
     workspace: 'List, view, and switch workspaces',
     doctor: 'Check token, connectivity, and workspace health',
-    agents: 'Supported agents, integration modes, and native plugin setup',
+    agents: 'Supported agents, integration modes, and native plugin setup',
     auth: 'Token types, bootstrap, refresh, resolution order',
     install: 'Install Empirical for Codex / Copilot / Claude Code',
     kit: 'Create, source, activate, and sync Skills Kits',

package/lib/env.js

@@ -1,49 +1,49 @@
-'use strict';
-
-const { ask } = require('./ui');
-
-function getEnv(name, fallback = '') {
-  return String(process.env[name] ?? fallback).trim();
-}
-
-function requireEnv(name) {
-  const value = getEnv(name);
-  if (!value) {
-    throw new Error(`Missing required env var: ${name}`);
-  }
-  return value;
-}
-
-async function resolveRequiredValueFromEnvOrPrompt(envName, promptLabel) {
-  const value = getEnv(envName);
-  if (value) return value;
-
-  if (!process.stdin.isTTY) {
-    throw new Error(`Missing required env var: ${envName}`);
-  }
-
-  const answer = (await ask(`${promptLabel}: `)).trim();
-  if (!answer) {
-    throw new Error(`${promptLabel} is required`);
-  }
-
-  return answer;
-}
-
-function parseFlag(args, flagName) {
-  return args.includes(flagName);
-}
-
-function parseOption(args, optionName, fallback = '') {
-  const index = args.indexOf(optionName);
-  if (index === -1) return fallback;
-  return String(args[index + 1] || '').trim() || fallback;
-}
-
-module.exports = {
-  getEnv,
-  requireEnv,
-  resolveRequiredValueFromEnvOrPrompt,
-  parseFlag,
-  parseOption
-};
+'use strict';
+
+const { ask } = require('./ui');
+
+function getEnv(name, fallback = '') {
+  return String(process.env[name] ?? fallback).trim();
+}
+
+function requireEnv(name) {
+  const value = getEnv(name);
+  if (!value) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+async function resolveRequiredValueFromEnvOrPrompt(envName, promptLabel) {
+  const value = getEnv(envName);
+  if (value) return value;
+
+  if (!process.stdin.isTTY) {
+    throw new Error(`Missing required env var: ${envName}`);
+  }
+
+  const answer = (await ask(`${promptLabel}: `)).trim();
+  if (!answer) {
+    throw new Error(`${promptLabel} is required`);
+  }
+
+  return answer;
+}
+
+function parseFlag(args, flagName) {
+  return args.includes(flagName);
+}
+
+function parseOption(args, optionName, fallback = '') {
+  const index = args.indexOf(optionName);
+  if (index === -1) return fallback;
+  return String(args[index + 1] || '').trim() || fallback;
+}
+
+module.exports = {
+  getEnv,
+  requireEnv,
+  resolveRequiredValueFromEnvOrPrompt,
+  parseFlag,
+  parseOption
+};

package/lib/help.js

@@ -18,8 +18,13 @@ function showHelp() {
   log('  empirical policy show [--refresh]');
   log('  empirical policy set --json <policy>');
   log('  empirical auth login                         Interactive browser login');
-  log('  empirical auth logout                        Clear the locally stored session');
+  log('  empirical auth logout [--local-only]         Revoke refresh tokens server-side, then clear the local session');
   log('  empirical auth status                        Print user, token type, expiry, workspace as JSON (alias: whoami)');
+  log('  empirical auth list-keys                     List the API keys on this account');
+  log('  empirical auth rotate-key [--label <name>] [--replace-all]');
+  log('                                               Mint a new API key (--replace-all wipes the existing ones)');
+  log('  empirical auth revoke-key (--key-id <id> | --all)');
+  log('                                               Revoke one API key, or every key on the account');
   log('  empirical oauth bootstrap headless [--print-access-token]');
   log('                                                First-time token setup for CI/headless/API-key use');
   log('  empirical oauth bootstrap headless --write-env [--env-output <path>]');