@terminus-ai/cli 0.0.1

package/bin/commands.mjs

@@ -0,0 +1,1194 @@
+/**
+ * Every `terminus` command, declared once: its group, one-line summary,
+ * usage, options, and examples. The help screens are rendered from this
+ * table and `parseFlags` enforces the same option lists (COMMAND_FLAGS), so
+ * help and behaviour cannot drift apart. Pure data plus string rendering:
+ * this module imports nothing.
+ *
+ * Options: `{ flag, value?, help, hidden? }`. A `value` placeholder makes it a
+ * string option; without one it is a boolean switch. Hidden options parse
+ * but never print (a transport detail: the web app a sign-in opens).
+ */
+import { DEFAULT_DEV_MEMBER } from "./dev-members.mjs";
+
+export const DOCS_URL = "https://www.terminus.build/docs/";
+
+const GROUPS = [
+  ["account", "Account"],
+  ["explore", "Explore"],
+  ["develop", "Developing"],
+  ["skills", "Install Skills"],
+  ["manage", "Management"],
+  ["operate", "Your published apps"],
+  ["releases", "Releases"],
+  ["meta", "Help"],
+];
+
+const JSON_OPTION = { flag: "json", help: "Print the result as JSON" };
+
+const SKILL_USE_OPTIONS = [
+  { flag: "select", value: "n", help: "Pick result <n> without asking" },
+  { flag: "use-first", help: "Pick the first result" },
+  { flag: "search", help: "Search even when the argument looks like an address" },
+  { flag: "limit", value: "n", help: "How many results to choose from (default: 5)" },
+  JSON_OPTION,
+];
+
+const SKILL_FETCH_OPTIONS = [
+  { flag: "refresh", help: "Download again even if the cache is current" },
+  JSON_OPTION,
+];
+
+/** Accepted by every command. Only --api-base prints; the web app a sign-in
+ * opens is a transport detail documented under Environment. A token never
+ * rides the command line (where the shell history and `ps` would keep it):
+ * TERMINUS_TOKEN is how automation passes one. */
+export const GLOBAL_OPTIONS = [
+  { flag: "api-base", value: "url", help: "Use another Terminus API (default: https://api.terminus.build)" },
+  { flag: "web-base", value: "url", help: "Terminus web app used for browser sign-in", hidden: true },
+];
+
+export const COMMANDS = [
+  // ── Account ──────────────────────────────────────────────────────────
+  {
+    name: "login",
+    group: "account",
+    summary: "Sign in to Terminus in your browser",
+    usage: ["terminus login [--no-browser]"],
+    about:
+      "Opens the Terminus sign-in page and waits for you to approve this device. "
+      + "The session lasts seven days; you can see and revoke it on the web in "
+      + "System Settings → General → Devices. If you are already signed in, login "
+      + "just says who you are.",
+    options: [
+      { flag: "no-browser", help: "Print the sign-in link instead of opening a browser" },
+      { flag: "web-base", value: "url", help: "Sign in through a local web app (with --api-base)" },
+    ],
+  },
+  {
+    name: "logout",
+    group: "account",
+    summary: "Sign out and revoke this device's session",
+    usage: ["terminus logout"],
+    options: [],
+  },
+  {
+    name: "account",
+    group: "account",
+    summary: "Your account's station",
+    usage: ["terminus account [--json]"],
+    about:
+      "Says hi by name and address, then counts what is waiting for you: "
+      + "unread notifications and invitations (what the notification box on "
+      + "the web holds) and the creations you have published. Exits with "
+      + "status 3 when you are not signed in, so scripts can check.",
+    options: [JSON_OPTION],
+  },
+  {
+    name: "notifications",
+    group: "account",
+    summary: "Check your notifications",
+    usage: ["terminus notifications [--all] [--limit <n>]"],
+    about:
+      "What the notification box on the web holds: invitations to collaborate "
+      + "or to join a chat, then unread notifications, newest first. Reading "
+      + "them here does not mark them read.",
+    options: [
+      { flag: "all", help: "Include notifications you have already read" },
+      { flag: "limit", value: "n", help: "How many notifications to show (default: 20)" },
+      JSON_OPTION,
+    ],
+  },
+  {
+    name: "creations",
+    group: "manage",
+    summary: "Manage your published creations",
+    usage: ["terminus creations [--json]"],
+    about:
+      "Your published apps, agents, services, and skills with their addresses "
+      + "and live versions, as Creations on the web lists them; any that "
+      + "Terminus has suspended are listed apart. Drafts are in terminus drafts.",
+    options: [JSON_OPTION],
+  },
+  {
+    name: "drafts",
+    group: "manage",
+    summary: "Manage your drafts",
+    usage: ["terminus drafts [--json]"],
+    about:
+      "Your apps, agents, services, and skills that have not been published "
+      + "yet. terminus clone <address> gets you a copy to work in and terminus "
+      + "push sends changes back; each is published from its page on the web.",
+    options: [JSON_OPTION],
+  },
+
+  // ── Developing ──────────────────────────────────────────────────────
+  {
+    name: "init",
+    group: "develop",
+    summary: "Create a new app, agent, service, or skill",
+    usage: [
+      "terminus init app|agent|service|skill [<dir>] [<options>]",
+      "terminus init [<dir>] --kind <kind> [<options>]",
+    ],
+    about:
+      "Scaffolds a package in <dir> (default: the current folder). Without a kind, "
+      + "init creates a skill. In a folder cloned from an empty creation it fills "
+      + "the folder in and keeps its link.",
+    options: [
+      { flag: "kind", value: "kind", help: "app, agent, service, or skill (same as the first argument)" },
+      { flag: "template", value: "name", help: "App starter: vanilla (default), react, or svelte" },
+      { flag: "name", value: "name", help: "Package name (default: the folder name)" },
+      { flag: "description", value: "text", help: "One-line description (skills)" },
+      { flag: "force", help: "Overwrite an existing terminus.json or SKILL.md" },
+      { flag: "json", help: "Print the result as JSON (skills)" },
+    ],
+    examples: [
+      "terminus init app my-app --template react",
+      "terminus init agent support-bot",
+      "terminus init skill slides --description \"Build slide decks from notes\"",
+    ],
+  },
+  {
+    name: "clone",
+    group: "develop",
+    summary: "Copy a creation into a new folder",
+    usage: ["terminus clone <address> [<dir>] [--template <name>]"],
+    about:
+      "Downloads the current draft of your own app, agent, service, or skill into "
+      + "<dir> (default: its slug), linked to it and ready to develop and push. "
+      + "Creations are made on the web, which gives each its address. A creation "
+      + "with nothing in it yet is started from a template on the spot — its kind "
+      + "was chosen when it was made, so the folder arrives ready to run instead "
+      + "of empty. Someone else's open-source creation clones read-only — its "
+      + "latest release, updated with pull, never pushed; to make changes you can "
+      + "publish, use terminus fork.",
+    options: [
+      { flag: "template", value: "name", help: "App starter for an empty creation: vanilla (default), react, or svelte" },
+      JSON_OPTION,
+    ],
+    examples: [
+      "terminus clone @you/my-app",
+      "terminus clone @you/my-app --template react",
+    ],
+  },
+  {
+    name: "fork",
+    group: "develop",
+    summary: "Fork someone's open-source creation and clone it",
+    usage: [
+      "terminus fork <address> [<dir>] [--version <version>] [--slug <slug>]",
+      "terminus fork <address> --no-clone",
+    ],
+    about:
+      "Makes the fork on Terminus, the way GitHub's Fork does: a draft of the "
+      + "same kind at @you/<slug> in your Creations, open source, with \"Forked "
+      + "from\" on its pages. Then clones it into <dir>, ready to push. One fork "
+      + "per account: forking again answers with yours. Only open-source apps, "
+      + "agents, and skills fork, and a fork with a price is bought on the web.",
+    options: [
+      { flag: "no-clone", help: "Make the fork on Terminus, but do not clone it" },
+      { flag: "version", value: "version", help: "Fork this release, by number or version, like 1.2.0 (default: the latest)" },
+      { flag: "slug", value: "slug", help: "Slug for your fork (apps and agents; default: the original's)" },
+      JSON_OPTION,
+    ],
+    examples: [
+      "terminus fork @acme/ledger",
+      "terminus fork @acme/ledger --slug my-ledger",
+      "terminus fork @acme/ledger --version 1.2.0",
+      "terminus fork @acme/ledger --no-clone",
+    ],
+  },
+  {
+    name: "remote",
+    group: "develop",
+    summary: "Show or change the creation a folder is connected to",
+    usage: [
+      "terminus remote [<dir>]",
+      "terminus remote add <address> [<dir>]",
+      "terminus remote remove [<dir>]",
+    ],
+    about:
+      "The creation a folder belongs to, the way git remote is a repository's. "
+      + "On its own it says which creation that is and which commit the folder "
+      + "matches, reading only what the folder holds. add records it — its "
+      + "address in terminus.json, or its id in a skill's SKILL.md — and "
+      + "uploads nothing; make the creation on the web first, which is what "
+      + "gives it the address. remove disconnects the folder and leaves every "
+      + "file where it is.",
+    options: [JSON_OPTION],
+    examples: ["terminus remote", "terminus remote add @you/my-app"],
+    subcommands: [
+      {
+        name: "add",
+        summary: "Connect this folder to a creation",
+        usage: ["terminus remote add <address> [<dir>]"],
+        options: [JSON_OPTION],
+        examples: ["terminus remote add @you/my-app"],
+      },
+      {
+        name: "remove",
+        summary: "Disconnect this folder, keeping its files",
+        usage: ["terminus remote remove [<dir>]"],
+        options: [JSON_OPTION],
+      },
+    ],
+  },
+  {
+    name: "dev",
+    group: "develop",
+    summary: "Run a package on this machine",
+    usage: [
+      "terminus dev [<dir>] [<options>]",
+      "terminus dev [<dir>] --remote",
+      "terminus dev [<dir>] --prompt <text> [--json]",
+    ],
+    about:
+      "What runs depends on the package in <dir> (default: the current folder):\n"
+      + "  app      the built bundle on a local runtime with fixture data\n"
+      + "           (run npm run build first)\n"
+      + "  agent    a chat page in your browser; the agent's tools run in a\n"
+      + "           sandbox on this machine\n"
+      + "  service  the package's dev/ test page, calling your deployed endpoint\n"
+      + "\n"
+      + "An app is served the same runtime it is served in production — the same "
+      + "doors, the same SDK — against fixture data kept in .terminus/dev/, so "
+      + "nothing you do here touches anyone's real data. It survives restarts, "
+      + "and --fresh starts it empty again.\n"
+      + "\n"
+      + "--members runs the app as several people at once. Each gets a port of "
+      + "their own (8868, 8869, and up), a name, and their own data, and they "
+      + "share one live event bus: open two of the ports side by side and watch "
+      + "a message, an invitation, or an edit cross between them. That is how "
+      + "you develop anything people do together, before it is published.\n"
+      + "\n"
+      + "--guest adds one more port, after the members': a visitor who is not "
+      + "signed in, as an app open to guests meets one. The app gets a guest's "
+      + "bootstrap there, its own files and the capability assets it declares, "
+      + "and every other door answers 401. Its sign-in (session.signIn()) opens "
+      + "a page that picks a member, and the port is that member until it signs "
+      + "out — the same origin throughout.\n"
+      + "\n"
+      + "With --remote, an app uses your real data on Terminus and an agent runs "
+      + "on the platform's engine; run it before publishing an agent that runs code.",
+    options: [
+      { flag: "port", value: "n", help: "Serve on this port; with --members, the first of a consecutive run" },
+      { flag: "no-open", help: "Do not open the browser (agents, services)" },
+      { flag: "remote", help: "Run against Terminus instead of this machine (apps, agents)" },
+      { flag: "members", value: "n|names", help: "Simulate several people: 3, or alice,bob (apps)" },
+      { flag: "guest", help: "Add a signed-out visitor's port after the members' (apps)" },
+      { flag: "profiles", value: "file", help: "Names and avatars for simulated members, as JSON (apps)" },
+      { flag: "fresh", help: "Start from empty fixture data (apps)" },
+      { flag: "prompt", value: "text", help: "Send one message, print the reply, and exit (agents)" },
+      { flag: "resume", value: "id", help: "Continue this conversation with --prompt (agents)" },
+      { flag: "trigger", value: "name", help: "Fire one of the agent's declared triggers and exit (agents)" },
+      { flag: "payload", value: "file", help: "JSON payload file for --trigger (agents)" },
+      { flag: "model", value: "model", help: "Override the agent's model (agents)" },
+      { flag: "sandbox", value: "mode", help: "Agents' sandbox: workspace-write, workspace-write-net, off" },
+      { flag: "agentd", value: "path", help: "Use this terminus-agentd binary (agents)" },
+      { flag: "json", help: "With --prompt or --trigger, print each event as one line of JSON" },
+    ],
+    examples: [
+      "npm run build && terminus dev",
+      "npm run build && terminus dev --members 3",
+      "terminus dev --members alice,bob --port 4000",
+      "terminus dev --members 2 --guest",
+      "terminus dev ./support-bot --prompt \"Summarize today's inbox\" --json",
+    ],
+  },
+  {
+    name: "build",
+    group: "develop",
+    summary: "Build an app's browser bundle",
+    usage: ["terminus build [<dir>]"],
+    about:
+      "Runs the build command configured in terminus.json, or copies ui/ to dist/ "
+      + "when there is none. push builds automatically; use this to check the "
+      + "build on its own.",
+    options: [JSON_OPTION],
+    examples: [
+      "terminus build",
+      "terminus build ./my-app",
+    ],
+  },
+  {
+    name: "validate",
+    group: "develop",
+    summary: "Check a package for problems before pushing",
+    usage: ["terminus validate [<dir>]"],
+    about:
+      "Checks an app, agent, or service package (terminus.json) or a skill "
+      + "(SKILL.md) the way Terminus will when you push. Works offline.",
+    options: [JSON_OPTION],
+    examples: [
+      "terminus validate",
+    ],
+  },
+  {
+    name: "status",
+    group: "develop",
+    summary: "Compare your working copy with its draft and live release",
+    usage: ["terminus status [<dir>]"],
+    about:
+      "Like git status: whether the draft has commits your copy hasn't pulled, "
+      + "which files you changed since it last matched, and anything a pull "
+      + "left for you to resolve. To see which account you are signed in as, "
+      + "use terminus account.",
+    options: [JSON_OPTION],
+    examples: [
+      "terminus status",
+      "terminus status ./my-app --json",
+    ],
+  },
+  {
+    name: "diff",
+    group: "develop",
+    summary: "Show your changes, or compare two releases",
+    usage: [
+      "terminus diff",
+      "terminus diff <address> [--from <version>] [--to <version>]",
+    ],
+    about:
+      "In a package folder, diff shows what you changed since the folder last "
+      + "matched its draft — what a push would send — the way git diff does. "
+      + "With an address it compares two published releases, each named by its "
+      + "version (1.2.0) or its release number: without --to, the latest with "
+      + "the one before it.",
+    options: [
+      { flag: "from", value: "version", help: "The older release (default: the one before --to)" },
+      { flag: "to", value: "version", help: "The newer release (default: the latest)" },
+      JSON_OPTION,
+    ],
+    examples: [
+      "terminus diff",
+      "terminus diff @acme/ledger --from 1.0.0 --to 1.1.0",
+    ],
+  },
+  {
+    name: "pull",
+    group: "develop",
+    summary: "Merge the draft's changes into your working copy",
+    usage: ["terminus pull [<dir>] [--force]"],
+    about:
+      "Brings in the draft's commits since your copy last matched it, the way "
+      + "git pull does: a file only the draft changed is taken, one only you "
+      + "changed is kept, and one both changed is merged line by line — "
+      + "terminus.json key by key. What cannot be merged is marked in the file "
+      + "and named; resolve it, then push. In a read-only copy, pull brings in "
+      + "newer releases.",
+    options: [
+      { flag: "force", help: "Replace your local files with the draft's instead of merging" },
+      JSON_OPTION,
+    ],
+    examples: [
+      "terminus pull",
+      "terminus pull --force",
+    ],
+  },
+  {
+    name: "push",
+    group: "develop",
+    summary: "Upload your working copy to its online draft",
+    usage: ["terminus push [<dir>] [--message <text>]"],
+    about:
+      "Updates the draft of the creation this folder is linked to — an app, "
+      + "agent, service, or skill — building an app first when it has a build "
+      + "step. Each push that changes something is one entry in the draft's "
+      + "history. What people are using never moves: push never publishes, and "
+      + "a creation is published from its page on the web, which push prints.",
+    options: [
+      { flag: "message", value: "text", help: "Say what changed; the draft's history shows it" },
+      { flag: "force", help: "Replace draft commits your copy hasn't pulled" },
+      JSON_OPTION,
+    ],
+    examples: [
+      "terminus push",
+      "terminus push --message \"Rooms can be renamed\"",
+    ],
+  },
+  {
+    name: "log",
+    group: "develop",
+    summary: "Show a draft's history, or a creation's releases",
+    usage: [
+      "terminus log [--limit <n>]",
+      "terminus log <address>",
+    ],
+    about:
+      "In a package folder, log lists its draft's commits, newest first — "
+      + "every push and every save on the web, with who made it, the message, "
+      + "and the versions published from it. With an address it lists that "
+      + "creation's releases.",
+    options: [
+      { flag: "limit", value: "n", help: "How many commits to show (default: 20)" },
+      JSON_OPTION,
+    ],
+    examples: [
+      "terminus log",
+      "terminus log @acme/ledger",
+    ],
+  },
+  {
+    name: "restore",
+    group: "develop",
+    summary: "Put the draft back the way it was at an earlier commit",
+    usage: ["terminus restore <commit> [<dir>] [--message <text>]"],
+    about:
+      "Restores the files, and the settings they compile to, of a commit "
+      + "terminus log shows. The restore is a new commit, like git revert: "
+      + "nothing is rewritten, and it can be undone the same way. A folder that "
+      + "matched the draft follows it; one with changes of its own pulls later.",
+    options: [
+      { flag: "message", value: "text", help: "Say why; the draft's history shows it" },
+      JSON_OPTION,
+    ],
+    examples: ["terminus log", "terminus restore 1a2b3c4d"],
+  },
+  {
+    name: "logs",
+    group: "develop",
+    summary: "Show a published app's recent logs",
+    usage: ["terminus logs <app> [--level <level>] [--limit <n>]"],
+    about: "<app> is the id, slug, or @handle/slug of an app you maintain.",
+    options: [
+      { flag: "level", value: "level", help: "Only entries at this level, such as error" },
+      { flag: "limit", value: "n", help: "How many entries to show" },
+      JSON_OPTION,
+    ],
+    examples: [
+      "terminus logs @you/my-app",
+    ],
+  },
+  {
+    name: "secrets",
+    group: "develop",
+    summary: "Manage sealed credentials for your package",
+    usage: ["terminus secrets list|set|delete [<name>] [<dir>]"],
+    about:
+      "Secrets are used by the outbound calls your linked package declares. "
+      + "Values are read from stdin (or $TERMINUS_SECRET_VALUE), never from the "
+      + "command line, and can never be read back.",
+    options: [JSON_OPTION],
+    subcommands: [
+      { name: "list", summary: "List the secrets that are set", usage: ["terminus secrets list [<dir>]"], options: [JSON_OPTION] },
+      {
+        name: "set",
+        summary: "Set or replace a secret (value from stdin)",
+        usage: ["terminus secrets set <name> [<dir>]"],
+        options: [JSON_OPTION],
+        examples: ["pbpaste | terminus secrets set OPENAI_API_KEY"],
+      },
+      { name: "delete", summary: "Delete a secret", usage: ["terminus secrets delete <name> [<dir>]"], options: [JSON_OPTION] },
+    ],
+  },
+  {
+    name: "data",
+    group: "develop",
+    summary: "Inspect, export, or import local dev data",
+    usage: ["terminus data inspect|export|import [<arguments>] [<options>]"],
+    about:
+      "Works on the fixture data terminus dev keeps in .terminus/dev/ for "
+      + `each simulated member (default member: ${DEFAULT_DEV_MEMBER}).`,
+    options: [],
+    subcommands: [
+      {
+        name: "inspect",
+        summary: "Summarize a member's local data",
+        usage: ["terminus data inspect [<dir>] [--member <name>] [--verify]"],
+        options: [
+          { flag: "member", value: "name", help: `Simulated member (default: ${DEFAULT_DEV_MEMBER})` },
+          { flag: "verify", help: "Also verify every stored object" },
+          JSON_OPTION,
+        ],
+      },
+      {
+        name: "export",
+        summary: "Copy a member's local data to a folder",
+        usage: ["terminus data export [<dir>] [<output-dir>] [--member <name>]"],
+        options: [
+          { flag: "member", value: "name", help: `Simulated member (default: ${DEFAULT_DEV_MEMBER})` },
+          { flag: "output", value: "dir", help: "Where to write the export (same as <output-dir>)" },
+          JSON_OPTION,
+        ],
+      },
+      {
+        name: "import",
+        summary: "Replace a member's local data from a folder",
+        usage: ["terminus data import [<dir>] <export-dir> [--member <name>] [--force]"],
+        about: "<export-dir> is a folder terminus data export wrote.",
+        options: [
+          { flag: "member", value: "name", help: `Simulated member (default: ${DEFAULT_DEV_MEMBER})` },
+          { flag: "force", help: "Replace existing data (a backup is kept)" },
+          JSON_OPTION,
+        ],
+      },
+    ],
+  },
+  {
+    name: "service",
+    group: "develop",
+    summary: "Inspect services, test operations, and run jobs",
+    usage: ["terminus service <command> [<arguments>] [<options>]"],
+    options: [],
+    subcommands: [
+      {
+        name: "inspect",
+        summary: "Show a service's operations and pricing",
+        usage: ["terminus service inspect <service>"],
+        options: [JSON_OPTION],
+      },
+      {
+        name: "test",
+        summary: "Call an operation of your local service package",
+        usage: ["terminus service test <dir> <operation> [<options>]"],
+        about:
+          "Uploads the package as your draft, then calls the operation through "
+          + "Terminus. Send a body with --file or --input.",
+        options: [
+          { flag: "file", value: "path", help: "Send this file as the request body" },
+          { flag: "input", value: "json", help: "Send this JSON as the request body" },
+          { flag: "query", value: "json", help: "Query parameters, as a JSON object" },
+          JSON_OPTION,
+        ],
+        examples: ["terminus service test . convert-document --file ./sample.docx"],
+      },
+      {
+        name: "submit",
+        summary: "Start a job on a published service",
+        usage: ["terminus service submit <service-id> <operation> [<options>]"],
+        about: "Needs --idempotency-key and exactly one of --input or --file.",
+        options: [
+          { flag: "input", value: "json", help: "The job's input" },
+          { flag: "file", value: "path", help: "Read the job's input from a JSON file" },
+          { flag: "idempotency-key", value: "key", help: "Any unique string; resubmitting it returns the same job" },
+          JSON_OPTION,
+        ],
+      },
+      {
+        name: "job",
+        summary: "Show a job's status and output",
+        usage: ["terminus service job <job-id> [--wait]"],
+        options: [
+          { flag: "wait", help: "Keep checking until the job finishes (up to 5 minutes)" },
+          JSON_OPTION,
+        ],
+      },
+      {
+        name: "jobs",
+        summary: "List your recent jobs",
+        usage: ["terminus service jobs [--service-id <uuid>]"],
+        options: [
+          { flag: "service-id", value: "uuid", help: "Only jobs for this service" },
+          JSON_OPTION,
+        ],
+      },
+      {
+        name: "cancel",
+        summary: "Cancel a queued or running job",
+        usage: ["terminus service cancel <job-id>"],
+        options: [JSON_OPTION],
+      },
+      {
+        name: "save",
+        summary: "Save a job's output file to your Terminus home folder",
+        usage: ["terminus service save <job-id> <file-id> <home-path> [<options>]"],
+        options: [
+          { flag: "expected-sha256", value: "hash", help: "Refuse to save unless the file has this hash" },
+          JSON_OPTION,
+        ],
+      },
+    ],
+  },
+  {
+    name: "connectors",
+    group: "develop",
+    summary: "List the connectors your agents can use",
+    usage: ["terminus connectors [<slug>]"],
+    about:
+      "Without a slug, lists each connector and the tool ids to declare in an "
+      + "agent's terminus.json. With a slug, shows its operations and the scopes "
+      + "they need.",
+    options: [JSON_OPTION],
+    examples: ["terminus connectors gmail"],
+  },
+
+  // ── Your published apps ─────────────────────────────────────────────
+  {
+    name: "inspect",
+    group: "operate",
+    summary: "Show a published app's runtime state",
+    usage: ["terminus inspect <app>"],
+    about: "<app> is the id, slug, or @handle/slug of an app you maintain.",
+    options: [JSON_OPTION],
+  },
+
+  // ── Releases ────────────────────────────────────────────────────────
+  {
+    name: "outdated",
+    group: "releases",
+    summary: "Check a creation's dependencies for newer releases",
+    usage: ["terminus outdated <address>"],
+    about:
+      "Lists the services, skills, and agents a published creation's release "
+      + "names, each with the version it pins and whether a newer release is "
+      + "out. Dependencies are recorded when a release is published.",
+    options: [JSON_OPTION],
+    examples: ["terminus outdated @you/my-app"],
+  },
+
+  // ── Skills ──────────────────────────────────────────────────────────
+  {
+    name: "search",
+    group: "explore",
+    summary: "Search the catalog",
+    usage: ["terminus search <query> [--kind <kind>] [--limit <n>]"],
+    about:
+      "Matches apps, agents, services, and skills by name and description, "
+      + "best match first.",
+    options: [
+      { flag: "kind", value: "kind", help: "Only skill, service, app, or agent results" },
+      { flag: "limit", value: "n", help: "How many results to show (default: 10)" },
+      JSON_OPTION,
+    ],
+    examples: ["terminus search \"browser automation\" --kind skill"],
+  },
+  {
+    name: "skills",
+    group: "skills",
+    summary: "Install and use skills in Claude Code or Codex",
+    usage: ["terminus skills <command> [<arguments>] [<options>]"],
+    options: [],
+    // Bare `terminus skills` (like `terminus help skills`) shows every skill
+    // command as a full line with what it does, the way `terminus help` shows
+    // the rest; `terminus help skills <command>` has the options. Tested like
+    // HELP_SECTIONS.
+    sections: [
+      ["Install Skills", [
+        ["terminus skills install <skill> --agent claude", "Add a skill to Claude Code"],
+        ["terminus skills install <skill> --agent codex", "Add a skill to Codex"],
+        ["terminus skills list", "List your installed skills"],
+        ["terminus skills update", "Update your installed skills"],
+        ["terminus skills uninstall <skill>", "Remove an installed skill"],
+      ]],
+      ["Use Skills", [
+        ["terminus skills use <skill>", "Load a skill for your agent"],
+        ["terminus skills use \"make a slide deck\"", "Find a skill for your task"],
+        ["terminus skills fetch <skill>", "Download a skill's files"],
+        ["terminus skills files <skill>", "List a skill's files"],
+        ["terminus skills file <skill> <path>", "Print one of a skill's files"],
+      ]],
+    ],
+    subcommands: [
+      {
+        name: "install",
+        summary: "Add a skill to Claude Code or Codex",
+        usage: ["terminus skills install <skill> [--agent <agent>] [<options>]"],
+        about:
+          "Writes a small pointer that loads the skill from Terminus each time it "
+          + "is used, so it stays current and every use counts. --agent picks the "
+          + "coding agent: claude, codex, or both (default: the agent you are "
+          + "running in, else claude). --local copies the whole package instead. "
+          + "Only open-source skills install: one whose content is closed is used "
+          + "on Terminus itself.",
+        options: [
+          { flag: "agent", value: "agent", help: "claude, codex, or both" },
+          { flag: "global", help: "Install for your user instead of this project" },
+          { flag: "dir", value: "dir", help: "Install into this folder instead" },
+          { flag: "local", help: "Copy the full package" },
+          { flag: "force", help: "Replace an existing install" },
+          JSON_OPTION,
+        ],
+        examples: [
+          "terminus skills install @zarazhangrui/frontend-slides --agent claude",
+          "terminus skills install @zarazhangrui/frontend-slides --agent codex --global",
+        ],
+      },
+      {
+        name: "list",
+        summary: "List the skills you have installed",
+        usage: ["terminus skills list"],
+        about:
+          "Every skill terminus installed, in this project and in your home "
+          + "folder, for Claude Code and Codex.",
+        options: [
+          { flag: "dir", value: "dir", help: "Only look in this folder" },
+          JSON_OPTION,
+        ],
+      },
+      {
+        name: "update",
+        summary: "Update the skills you have installed",
+        usage: ["terminus skills update [<skill>]"],
+        about:
+          "Checks every skill terminus installed, in this project and in your "
+          + "home folder, against Terminus. A pointer already loads the latest "
+          + "instructions each time it runs, so update refreshes the name, "
+          + "description, and address it carries. A --local copy downloads the "
+          + "new version, which counts as a use. Name a skill to update only that "
+          + "one.",
+        options: [
+          { flag: "dir", value: "dir", help: "Only look in this folder" },
+          JSON_OPTION,
+        ],
+      },
+      {
+        name: "uninstall",
+        summary: "Remove an installed skill",
+        usage: ["terminus skills uninstall <skill>"],
+        about: "Removes every install terminus made of the skill, in this project and in your home folder.",
+        options: [
+          { flag: "dir", value: "dir", help: "Only look in this folder" },
+          JSON_OPTION,
+        ],
+      },
+      {
+        name: "use",
+        summary: "Load a skill's instructions for your coding agent",
+        usage: ["terminus skills use <skill|query>"],
+        about:
+          "Given an address or id, loads that skill. Given words, searches and asks "
+          + "you to pick one. Each use is counted on your account. Installed skills "
+          + "run this when they trigger.",
+        options: SKILL_USE_OPTIONS,
+        examples: [
+          "terminus skills use @zarazhangrui/frontend-slides",
+          "terminus skills use \"make a slide deck\"",
+          "terminus skills use \"make a slide deck\" --use-first",
+        ],
+      },
+      {
+        name: "fetch",
+        summary: "Download a skill's files to the local cache",
+        usage: ["terminus skills fetch <skill> [--refresh]"],
+        about:
+          "Prints the cache folder. The files are reused until the skill changes; "
+          + "--refresh downloads them again.",
+        options: SKILL_FETCH_OPTIONS,
+      },
+      {
+        name: "files",
+        summary: "List a skill's files",
+        usage: ["terminus skills files <skill>"],
+        options: [JSON_OPTION],
+      },
+      {
+        name: "file",
+        summary: "Print one of a skill's files",
+        usage: ["terminus skills file <skill> <path>"],
+        options: [JSON_OPTION],
+      },
+    ],
+  },
+  // ── Help ────────────────────────────────────────────────────────────
+  {
+    name: "help",
+    group: "meta",
+    summary: "Show help for a command",
+    usage: ["terminus help [<command>] [<subcommand>]"],
+    options: [],
+  },
+  {
+    name: "commands",
+    group: "meta",
+    summary: "List every command",
+    usage: ["terminus commands"],
+    about:
+      "Every command with a one-line summary, then the options, environment "
+      + "variables, and exit codes all commands share. terminus help shows the "
+      + "everyday ones as examples.",
+    options: [],
+  },
+  {
+    name: "version",
+    group: "meta",
+    summary: "Print the CLI version",
+    usage: ["terminus version [--json]"],
+    about: "--json also names the @terminus-ai/app-sdk version new apps depend on.",
+    options: [JSON_OPTION],
+  },
+];
+
+/** One name per command: what help lists is what runs, and nothing else. */
+const BY_NAME = new Map(COMMANDS.map((command) => [command.name, command]));
+
+export function commandNamed(name) {
+  return BY_NAME.get(name) ?? null;
+}
+
+export function subcommandNamed(command, name) {
+  return command?.subcommands?.find((sub) => sub.name === name) ?? null;
+}
+
+function flagSpec(options) {
+  const booleans = [];
+  const strings = [];
+  for (const option of options) {
+    (option.value ? strings : booleans).push(option.flag);
+  }
+  return { booleans: [...new Set(booleans)], strings: [...new Set(strings)] };
+}
+
+/** Accepted by every command, on top of its own options. */
+export const COMMON_FLAGS = Object.freeze(flagSpec(GLOBAL_OPTIONS));
+
+/** What `parseFlags(args, name)` accepts: a command's options plus every
+ * option of its subcommands (the verb is stripped before parsing). */
+export const COMMAND_FLAGS = Object.freeze(Object.fromEntries(
+  COMMANDS.flatMap((command) => [
+    [
+      command.name,
+      Object.freeze(flagSpec([
+        ...command.options,
+        ...(command.subcommands ?? []).flatMap((sub) => sub.options ?? []),
+      ])),
+    ],
+    // "skills install": exactly that subcommand's options.
+    ...(command.subcommands ?? []).map((sub) => [
+      `${command.name} ${sub.name}`,
+      Object.freeze(flagSpec(sub.options ?? [])),
+    ]),
+  ]),
+));
+
+/* ── Did-you-mean ─────────────────────────────────────────────────────── */
+
+function editDistance(a, b) {
+  const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j += 1) rows[0][j] = j;
+  for (let i = 1; i <= a.length; i += 1) {
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        rows[i][j] = Math.min(rows[i][j], rows[i - 2][j - 2] + 1);
+      }
+    }
+  }
+  return rows[a.length][b.length];
+}
+
+/** The closest candidate within a small typo budget, or null. */
+export function closest(word, candidates) {
+  const wanted = String(word ?? "").toLowerCase();
+  if (!wanted) return null;
+  const budget = wanted.length <= 4 ? 1 : 2;
+  let best = null;
+  let bestDistance = Infinity;
+  for (const candidate of candidates) {
+    const distance = candidate.startsWith(wanted) && wanted.length >= 3 ? 0.5 : editDistance(wanted, candidate);
+    if (distance < bestDistance) {
+      best = candidate;
+      bestDistance = distance;
+    }
+  }
+  return bestDistance <= budget ? best : null;
+}
+
+/** A word that is not a command: the nearest one it might be, and where the
+ *  whole list is. A command this CLI no longer has is simply not a command —
+ *  nothing shipped under the old name, so nothing has to be explained. */
+export function unknownCommandMessage(name) {
+  const lines = [`terminus: '${name}' is not a terminus command.`];
+  const suggestion = closest(name, COMMANDS.filter((command) => !command.hidden).map((command) => command.name));
+  if (suggestion) lines.push(`Did you mean 'terminus ${suggestion}'?`);
+  lines.push("Run 'terminus commands' to see every command.");
+  return lines.join("\n");
+}
+
+/* ── Rendering ────────────────────────────────────────────────────────── */
+
+const WIDTH = 80;
+
+function wrap(text, indent = "", width = WIDTH) {
+  const out = [];
+  for (const paragraph of String(text).split("\n\n")) {
+    if (out.length) out.push("");
+    // Pre-formatted paragraphs (indented lists) keep their own line breaks.
+    if (/^ {2}/m.test(paragraph)) {
+      for (const line of paragraph.split("\n")) out.push(`${indent}${line}`);
+      continue;
+    }
+    let line = "";
+    for (const word of paragraph.replace(/\s+/g, " ").trim().split(" ")) {
+      if (line && indent.length + line.length + 1 + word.length > width) {
+        out.push(`${indent}${line}`);
+        line = word;
+      } else {
+        line = line ? `${line} ${word}` : word;
+      }
+    }
+    if (line) out.push(`${indent}${line}`);
+  }
+  return out;
+}
+
+/** Two aligned columns; a left cell too wide for the gutter puts its text on
+ * the next line instead of pushing every row right. */
+function table(rows, { indent = "  ", maxLeft = 24, width: fixed } = {}) {
+  const width = fixed ?? Math.min(maxLeft, Math.max(0, ...rows.map(([left]) => left.length)));
+  const pad = " ".repeat(indent.length + width + 2);
+  const out = [];
+  for (const [left, right] of rows) {
+    if (!right) {
+      out.push(`${indent}${left}`);
+      continue;
+    }
+    const text = wrap(right, "", WIDTH - pad.length);
+    const rest = text.slice(1).map((line) => `${pad}${line}`);
+    if (left.length > width) {
+      out.push(`${indent}${left}`, `${pad}${text[0] ?? ""}`, ...rest);
+    } else {
+      out.push(`${indent}${left.padEnd(width)}  ${text[0] ?? ""}`, ...rest);
+    }
+  }
+  return out;
+}
+
+function optionLabel(option) {
+  return option.value ? `--${option.flag} <${option.value}>` : `--${option.flag}`;
+}
+
+function visible(options = []) {
+  return options.filter((option) => !option.hidden);
+}
+
+/** `terminus help`: the commands people reach for, grouped, each with what
+ * it does, every row on one line in one column (`terminus help <command>`
+ * has the options). <angle> words are placeholders and [ ] is optional.
+ * Every row is checked against this registry by the tests; `terminus
+ * commands` lists everything. */
+export const HELP_SECTIONS = [
+  ["Account", [
+    ["terminus login", "Open your browser and sign in"],
+    ["terminus account", "Your account's station"],
+    ["terminus notifications", "Check your notifications"],
+  ]],
+  ["Explore", [
+    ["terminus search <query>", "Search the Terminus catalog"],
+  ]],
+  // In the order the work happens: start or connect a folder, run it, check
+  // it, compare it, push it, and watch it once it is published.
+  ["Developing", [
+    ["terminus init <kind> [<dir>]", "Start a new creation"],
+    ["terminus clone <address> [<dir>]", "Download a creation to edit"],
+    ["terminus remote add <address> [<dir>]", "Connect a folder to a creation"],
+    ["terminus dev [<dir>]", "Mock your creation locally"],
+    ["terminus validate [<dir>]", "Check a package for problems"],
+    ["terminus status [<dir>]", "Compare your copy with Terminus"],
+    ["terminus pull [<dir>]", "Merge the draft's changes into yours"],
+    ["terminus push [<dir>]", "Upload your changes as a draft"],
+    ["terminus logs <app>", "Show a published app's logs"],
+  ], [
+    {
+      // Two arcs, and only the arcs: get it, run it, push it. There is no
+      // list of keys above them any more — it named --members and --prompt,
+      // then the walkthroughs said both again in the one place they mean
+      // something, beside the run they change. A key read next to its own
+      // command needs no explaining, and the list was four lines of saying
+      // it twice. `status` is a question you ask, not a step you take, and
+      // it is one row up.
+      title: "Mock it locally so your coding agent can test end to end — an app:",
+      lines: [
+        "terminus clone @you/app && cd app",
+        "npm run build                        # apps are built before they run",
+        "terminus dev --members 3             # three at once; --fresh to start empty",
+        "terminus push --message \"Rooms can be renamed\"",
+      ],
+    },
+    {
+      title: "An agent, which has no build step:",
+      lines: [
+        "terminus clone @you/agent && cd agent",
+        "terminus dev                         # a chat page; --remote for real data",
+        "terminus dev --prompt \"Two lines on today's inbox\"",
+        "terminus push --message \"Sharper summary\"",
+      ],
+    },
+    {
+      // What is left once every key has been shown in use: where to read the
+      // ones that were not.
+      // Not opened with "terminus ": every line that starts that way in this
+      // screen is a row of the table above, with its explanation in the
+      // shared column, and the overview test holds it to that.
+      title: "Every other key, --port included, and what each kind runs: terminus help dev",
+      lines: [],
+    },
+  ]],
+  ["Install Skills", [
+    ["terminus skills", "Install skills in Claude Code or Codex"],
+  ]],
+  ["Management", [
+    ["terminus creations", "Manage your published creations"],
+    ["terminus drafts", "Manage your drafts"],
+  ]],
+  ["Further help", [
+    ["terminus commands", "List every command"],
+    ["terminus help [<command>]", "Show how to use a command"],
+    [DOCS_URL, ""],
+  ]],
+];
+
+/** One command column for the whole screen, as wide as its longest row, so
+ * every description starts at the same place. */
+const HELP_COLUMN = Math.max(
+  ...HELP_SECTIONS.flatMap(([, rows]) => rows.filter(([, text]) => text).map(([usage]) => usage.length)),
+);
+
+/** `version` puts "Terminus v0.0.1, created by Terminus Intelligence" on
+ * top, the way bare `terminus` opens. */
+export function renderOverview({ version } = {}) {
+  const body = HELP_SECTIONS
+    .map(([title, rows, blocks = []]) => [
+      `${title}:`,
+      ...table(rows, { width: HELP_COLUMN }),
+      ...blocks.flatMap((block) => [
+        "",
+        `  ${block.title}`,
+        ...block.lines.map((line) => `    ${line}`),
+      ]),
+    ].join("\n"))
+    .join("\n\n");
+  return version ? `Terminus v${version}, created by Terminus Intelligence\n\n${body}` : body;
+}
+
+/** `terminus commands`: every command, grouped, one line each, then what all
+ * of them accept. */
+export function renderCommands() {
+  const lines = ["Usage: terminus <command> [<arguments>] [<options>]"];
+  // One name column for every group, so the summaries line up down the page.
+  const width = Math.max(...COMMANDS.filter((command) => !command.hidden).map((command) => command.name.length));
+  for (const [group, title] of GROUPS) {
+    const commands = COMMANDS.filter((command) => command.group === group && !command.hidden);
+    if (!commands.length) continue;
+    lines.push("", `${title}:`, ...table(commands.map((command) => [command.name, command.summary]), { width }));
+  }
+  lines.push(
+    "",
+    "Options:",
+    ...table([
+      ["-h, --help", "Show help for terminus or a command"],
+      ["-v, --version", "Print the CLI version"],
+      ["--json", "Print machine-readable output (most commands)"],
+      ...visible(GLOBAL_OPTIONS).map((option) => [optionLabel(option), option.help]),
+    ]),
+    "",
+    "Environment:",
+    ...table([
+      ["TERMINUS_TOKEN", "Use this access token instead of your saved login"],
+      ["TERMINUS_API_BASE", "Same as --api-base"],
+    ]),
+    "",
+    "Exit codes:",
+    "  0 success, 1 error, 2 bad usage, 3 not signed in, 69 Terminus unreachable,",
+    "  75 rate limited, 77 not allowed. With --json, errors are printed to stderr",
+    "  as JSON.",
+    "",
+    "Run 'terminus help <command>' for details on a command.",
+    `Docs: ${DOCS_URL}`,
+  );
+  return lines.join("\n");
+}
+
+/** "Search the catalog." — help prose and option text read as sentences. */
+function sentence(text) {
+  const trimmed = String(text ?? "").trim();
+  return !trimmed || /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+
+/** The summary leads the prose, joined to the first paragraph of `about`
+ * unless that paragraph is a pre-formatted list. */
+function describe(entry) {
+  const summary = sentence(entry.summary);
+  if (!entry.about) return summary;
+  const [first, ...rest] = entry.about.split("\n\n");
+  if (/^ {2}/m.test(first)) return `${summary}\n\n${entry.about}`;
+  return [`${summary} ${first}`, ...rest].join("\n\n");
+}
+
+/** One command's help, the way `brew search --help` reads: usage, prose,
+ * then every option (long-only flags indented past `-h, `). */
+function renderEntry(entry) {
+  const lines = entry.usage.map((usage, index) => `${index ? "       " : "Usage: "}${usage}`);
+  lines.push("", ...wrap(describe(entry)));
+  if (entry.sections?.length) {
+    // Full command lines, sectioned like `terminus help`, in one column.
+    const width = Math.max(...entry.sections.flatMap(([, rows]) => rows.map(([usage]) => usage.length)));
+    for (const [title, rows] of entry.sections) {
+      lines.push("", `${title}:`, ...table(rows, { width }));
+    }
+  } else if (entry.subcommands?.length) {
+    lines.push(
+      "",
+      "Commands:",
+      ...table(entry.subcommands.map((sub) => [sub.name, sub.summary]), { maxLeft: 10 }),
+    );
+  }
+  const options = [
+    ...visible(entry.options).map((option) => [`    ${optionLabel(option)}`, sentence(option.help)]),
+    ["-h, --help", "Show this message."],
+  ];
+  lines.push("", ...table(options, { maxLeft: 28 }));
+  if (entry.examples?.length) {
+    lines.push("", entry.examples.length === 1 ? "Example:" : "Examples:", ...entry.examples.map((example) => `  ${example}`));
+  }
+  if (entry.subcommands?.length) {
+    lines.push("", `Run 'terminus help ${entry.name} <command>' for details on a command.`);
+  }
+  return lines.join("\n");
+}
+
+/** "This command requires <query>." — what a usage line demands outside
+ * its [ ], for bad-usage errors. */
+export function missingArgumentReason(entry) {
+  const words = entry.usage[0].split(" ");
+  const required = [];
+  let depth = 0;
+  for (const word of words.slice(words.indexOf(entry.name) + 1)) {
+    const outside = depth === 0 && !word.startsWith("[") && !word.startsWith("--");
+    depth += (word.match(/\[/g) ?? []).length - (word.match(/\]/g) ?? []).length;
+    if (outside) required.push(word);
+  }
+  if (!required.length) return "This command takes different arguments.";
+  if (required.length === 1 && !required[0].startsWith("<")) {
+    return `This command requires one of: ${required[0].split("|").join(", ")}.`;
+  }
+  const list = required.length === 1 ? required[0] : `${required.slice(0, -1).join(", ")} and ${required.at(-1)}`;
+  return `This command requires ${list}.`;
+}
+
+/** Help for `terminus help [<command>] [<subcommand>]`; throws on an unknown topic
+ * so the caller can exit with the usage code. */
+export function renderHelp(topic = []) {
+  const [name, subName] = topic;
+  if (!name) return renderOverview();
+  const command = commandNamed(name);
+  if (!command) {
+    const error = new Error(unknownCommandMessage(name));
+    error.usage = true;
+    throw error;
+  }
+  if (subName && command.subcommands?.length) {
+    const sub = subcommandNamed(command, subName);
+    if (!sub) {
+      const error = new Error(
+        `terminus ${name}: '${subName}' is not a command. Commands: ${command.subcommands.map((entry) => entry.name).join(", ")}.`,
+      );
+      error.usage = true;
+      throw error;
+    }
+    return renderEntry(sub);
+  }
+  return renderEntry(command);
+}
+
+/** True when `-h`/`--help` appears as a switch rather than as the value of a
+ * string option (`--prompt -h` sends "-h"). */
+export function helpRequested(name, args) {
+  const strings = new Set([...(COMMAND_FLAGS[name]?.strings ?? []), ...COMMON_FLAGS.strings]);
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") return true;
+    if (arg.startsWith("--") && !arg.includes("=") && strings.has(arg.slice(2))) index += 1;
+  }
+  return false;
+}