@pome-sh/cli 0.33.0 → 0.33.1

package/README.md

@@ -11,7 +11,7 @@ prints it to the terminal and records it to the dashboard, and
 
 **📚 Full documentation lives at [docs.pome.sh](https://docs.pome.sh).**
 Run `pome --help` (or `pome help <command>`) for the CLI reference, and
-`pome docs getting-started` to open the canonical quickstart.
+`pome docs getting-started` to print the quickstart's URL.
 
 ## Install
 
@@ -40,7 +40,7 @@ local/OSS package release.
 
 ```bash
 pome login                       # one-time; opens the dashboard to sign in
-pome init                        # scaffolds tasks/, examples/agents/, runs/, pome.config.json
+pome init                        # scaffolds tasks/, examples/agents/, runs/, pome.json
 pome register agent my-agent     # scopes runs to this project
 pome run tasks/01-bug-happy-path.md --agent "node examples/agents/scripted-triage-agent.ts"
 pome inspect latest              # trace/audit view of the last run
@@ -49,7 +49,7 @@ pome inspect latest              # trace/audit view of the last run
 To capture a trace without the cloud (self-host), then get a verdict later:
 
 ```bash
-pome run --local tasks/01-bug-happy-path.md   # captures a raw trace only — no verdict
+pome run --local tasks/01-bug-happy-path.md   # captures a raw trace only, no verdict
 pome eval runs/01-bug-happy-path/<run-id>         # uploads it for a cloud verdict
 ```
 

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "package": "pome-sh",
-  "version": "0.33.0",
-  "git_sha": "19a5eae0c7dd814492b7813601d621b22ee078e7",
-  "build_time": "2026-08-28T02:16:12.366Z"
+  "version": "0.33.1",
+  "git_sha": "15d61b80f3fb2ee0df893ca81c0c9e4d0afd0076",
+  "build_time": "2026-08-28T11:26:59.938Z"
 }

package/dist/src/cli/main.js

@@ -4622,7 +4622,7 @@ var DEFAULT_AGENT_COMMAND = `node ${DEFAULT_AGENT_FILE}`;
 var MANIFEST_SCHEMA_URL = "https://pome.sh/schemas/v1/pome.json";
 var MAX_UNREADABLE_PATHS_SHOWN = 5;
 function readPackageVersion() {
-  if ("0.33.0".length > 0) return "0.33.0";
+  if ("0.33.1".length > 0) return "0.33.1";
   try {
     const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [
@@ -4643,9 +4643,9 @@ function readPackageVersion() {
 function createProgram() {
   const program = new Command();
   program.name("pome").description(
-    "Digital-twin testing for AI agents \u2014 `pome run` records to app.pome.sh. See `pome docs getting-started`."
+    "Test AI agents against digital twins of real SaaS APIs. Runs are recorded to app.pome.sh. Start with `pome demo`."
   ).version(PACKAGE_VERSION).showHelpAfterError("(add --help for usage)");
-  program.command("init").description("Create starter Pome config and folders").option(
+  program.command("init").summary("Set up Pome in this project").description("Create pome.json, plus starter files in a new project").option(
     "--sdk <name>",
     "Scaffold for a specific agent SDK (claude | claude-managed). Adds the SDK-specific example file and pre-fills agent.framework so the dashboard badges runs correctly."
   ).option(
@@ -4720,7 +4720,7 @@ function createProgram() {
     }
     console.error(postInitMessage);
   });
-  program.command("login").description("Sign in with Clerk and store a hosted team API key (macOS Keychain or ~/.pome/credentials.json)").option(
+  program.command("login").summary("Sign in and save an API key").description("Sign in with Clerk and store a hosted team API key (macOS Keychain or ~/.pome/credentials.json)").option(
     "--api-url <url>",
     "Control-plane base URL.",
     process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL
@@ -4737,14 +4737,14 @@ function createProgram() {
       await loginWithClerk(options);
     }
   );
-  program.command("logout").description("Remove locally stored hosted credentials (Keychain entry and/or ~/.pome/credentials.json)").action(async () => {
+  program.command("logout").summary("Delete the saved API key").description("Remove locally stored hosted credentials (Keychain entry and/or ~/.pome/credentials.json)").action(async () => {
     await clearLocalCredentials();
     console.error("Removed local Pome credentials.");
     console.error(
       "Server-side keys are not auto-revoked \u2014 revoke API keys from the dashboard if this device was lost."
     );
   });
-  program.command("docs").argument("[topic]", "Topic id (e.g. getting-started, github, cli) \u2014 prints the docs.pome.sh URL").option(
+  program.command("docs").summary("Print a docs.pome.sh URL by topic").argument("[topic]", "Topic id (e.g. getting-started, github, cli) \u2014 prints the docs.pome.sh URL").option(
     "--site <origin>",
     "Override docs site origin (default https://docs.pome.sh)"
   ).option(
@@ -4756,7 +4756,7 @@ function createProgram() {
   ).action(async (topic, opts) => {
     await runDocsCommand(topic, { site: opts.site, urlOnly: Boolean(opts.url) });
   });
-  program.command("tasks").argument(
+  program.command("tasks").summary("List or copy the bundled tasks").argument(
     "[twin]",
     "Twin id (e.g. github). Omit to list available twins."
   ).option(
@@ -4781,7 +4781,7 @@ function createProgram() {
       });
     }
   );
-  const checks = program.command("checks").argument("[twin]", "Twin id (e.g. github). Omit to list twins that declare checks.").option("--json", "Emit the declaration as JSON (for skills and agents).", false).description(
+  const checks = program.command("checks").summary("List, add, and lint a twin's checks").argument("[twin]", "Twin id (e.g. github). Omit to list twins that declare checks.").option("--json", "Emit the declaration as JSON (for skills and agents).", false).description(
     "Browse the typed checks a twin declares \u2014 the closed set a [code] criterion is graded by"
   ).action(async (twin2, opts) => {
     await runChecksCommand(twin2, { json: opts.json });
@@ -4807,7 +4807,7 @@ function createProgram() {
   checks.command("lint").argument("<file...>", "Task markdown file(s) \u2014 shell globs work: tasks/*.md").description("Report [code] criteria that bind no declared check, so are never graded").action(async (files) => {
     await runChecksLintCommand(files);
   });
-  program.command("compile-seeds").argument("[target]", "Task .md file or directory (defaults to ./tasks)").option("--force", "Recompile even if the sidecar's source hash matches", false).option(
+  program.command("compile-seeds").summary("Compile a task's seed state to JSON").argument("[target]", "Task .md file or directory (defaults to ./tasks)").option("--force", "Recompile even if the sidecar's source hash matches", false).option(
     "--hosted",
     "Compile via the Pome control plane instead of calling Anthropic directly (uses your Pome API key; no ANTHROPIC_API_KEY needed)",
     false
@@ -4825,7 +4825,7 @@ function createProgram() {
     });
     if (code !== 0) process.exitCode = code;
   });
-  const register = program.command("register").description(
+  const register = program.command("register").summary("Register an agent with Pome").description(
     "Register a cloud entity (agent, ...) and link this project to it"
   );
   register.command("agent").argument("<name>", 'Human-readable agent name (e.g. "triage-bot")').option(
@@ -4857,7 +4857,7 @@ function createProgram() {
       }
     }
   );
-  const session = program.command("sandbox").description(
+  const session = program.command("sandbox").summary("Create, list, and stop sandboxes").description(
     "Hosted sandboxes (same API as the dashboard Twins page \u2014 requires login)"
   );
   session.command("create").description("Create a hosted sandbox for one or more twins and print its connection info").option(
@@ -4972,7 +4972,7 @@ function createProgram() {
       }
     }
   );
-  program.command("run").argument(
+  program.command("run").summary("Run a task and print the score").argument(
     "[path]",
     'Task markdown file or directory. Omit to run the demo task ("that was ours, run yours"): tasks/first-run-demo.md is dropped into your project on first use with runs: 5 pinned.'
   ).option("--agent <command>", "Agent command to run").option(
@@ -5183,7 +5183,7 @@ function createProgram() {
       process.exitCode = worstExit;
     }
   );
-  program.command("demo").description(
+  program.command("demo").summary("Run a sample task, no account needed").description(
     "Zero-auth first-run demo: boots a local GitHub twin, runs the bundled demo agent for 5 isolated trials (model calls via pome's anonymous demo gateway), and prints per-trial verdicts evaluated in Pome cloud. No signup, no API keys; ends with a no-login preview link."
   ).option(
     "--api-url <url>",
@@ -5216,7 +5216,7 @@ function createProgram() {
     const code = await runDemoAgentCommand();
     if (code !== 0) process.exitCode = code;
   });
-  program.command("doctor").description(
+  program.command("doctor").summary("Check the agent and twin wiring").description(
     "Check the agent\u2194twin wiring: pome.json (or pome.yaml) present + valid, the local twin boots + serves, requests routed to the twin (not a hardcoded production host), egress floor active. On failure prints one named cause (file:line where knowable) + one concrete fix and exits non-zero."
   ).action(async () => {
     const { runDoctorChecks } = await import('../../checks-CAP2CSEW.js');
@@ -5225,7 +5225,7 @@ function createProgram() {
     for (const line of renderDoctorReport(report, { passNote: true })) console.error(line);
     if (!report.ok) process.exitCode = 1;
   });
-  program.command("eval").argument(
+  program.command("eval").summary("Score a trace recorded earlier").argument(
     "[run-dir]",
     "Existing run directory (runs/<task>/<run-id>). Omit to use <artifacts-dir>/latest.json."
   ).option(
@@ -5267,7 +5267,7 @@ function createProgram() {
       for (const line of renderEvents(eventsResult.events)) console.log(line);
     }
   });
-  program.command("fix-prompt").argument(
+  program.command("fix-prompt").summary("Build a prompt for a failed run").argument(
     "[target]",
     "Artifacts root or a trial run dir (default: runs). Legacy form: a path to events.jsonl \u2014 then <task> is required."
   ).argument(
@@ -5383,7 +5383,7 @@ function createProgram() {
       })
     );
   });
-  const twin = program.command("twin").description("Manage local twins");
+  const twin = program.command("twin").summary("Run a twin on this machine").description("Start and reset a twin on this machine, print its status or a starter seed file");
   twin.command("start").argument(
     "[name]",
     `Twin name (${TWIN_NAME_LIST.join(" | ")}). Optional when --seed names exactly one twin.`
@@ -5428,7 +5428,7 @@ function createProgram() {
     }
     console.log(await import('node:fs/promises').then((fs) => fs.readFile(".pome/twin-status.json", "utf8")));
   });
-  program.command("endpoints").argument("<name>", "Twin name").description("List supported endpoints").action((name) => {
+  program.command("endpoints").summary("List a twin's endpoints").argument("<name>", "Twin name").description("List the endpoints the github or gmail twin serves").action((name) => {
     const endpoints = name === "github" ? SUPPORTED_GITHUB_ENDPOINTS : name === "gmail" ? SUPPORTED_GMAIL_ENDPOINTS : null;
     if (!endpoints) {
       throw new Error("Endpoint listing is available for: github, gmail.");
@@ -5437,7 +5437,7 @@ function createProgram() {
       console.log(`${endpoint}  semantic`);
     }
   });
-  program.command("capture-server").description(
+  program.command("capture-server").summary("Record the agent's model calls").description(
     "Boot an HTTP CONNECT-tunnel proxy that appends one LlmCallEvent per tunnel to events.jsonl. Spawned by `pome run`; agent traffic flows via HTTPS_PROXY."
   ).option("--port <port>", "TCP port to listen on (0 = ephemeral).", "8910").option(
     "--events-out <path>",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pome-sh/cli",
-  "version": "0.33.0",
-  "description": "Digital-twin testing for AI agents \u2014 run tasks against resettable local or hosted twins and record tool-call traces for evaluation on pome.sh.",
+  "version": "0.33.1",
+  "description": "Test AI agents against digital twins of real SaaS APIs. Records tool-call traces and scores them on pome.sh.",
   "keywords": [
     "ai",
     "agents",