@ours.network/cli 0.1.0 → 0.2.0

package/README.md

@@ -10,13 +10,45 @@ separate package above `@ours.network/sdk`: lifecycle commands call
 ```bash
 npm install --global @ours.network/cli
 ours version
+ours help
 ours config show --json
 ours daemon status --json
 ```
 
-Node 20 or newer is required. `--json` emits one JSON value on stdout; errors
-are JSON on stderr. Status exits `0` while running and `3` while stopped. Usage
-errors exit `2`; other failures exit `1`.
+Node 20 or newer is required. `--json` emits one JSON value on stdout, except
+`daemon watch`, which streams one JSON event per line (JSONL); errors are JSON
+on stderr. Status exits `0` while running and `3` while stopped. Usage errors
+exit `2`; other failures exit `1`.
+
+For a new host, configure safe daemon settings, start the shared daemon, create
+the Human identity, and then add agent roles:
+
+```bash
+ours config setup --port 3070 --state-dir "$HOME/.ours/state"
+ours daemon start
+ours daemon status --json
+ours identity create-root --name Alice@laptop
+ours identity create --name BuildBot --bio "Build coordinator"
+```
+
+## Help and command discovery
+
+The CLI help is the complete operator reference. A bare command group shows its
+subcommands, and both help forms reach the same command-specific page without
+connecting to a daemon or performing the requested action:
+
+```bash
+ours identity
+ours identity create --help
+ours help identity create
+ours help api send-file
+```
+
+Specific help lists every accepted flag, required fields, defaults, enum and
+XOR rules, side effects, safety confirmation, and a credential-free example.
+Parser-compatible flags that an action does not consume are labeled
+`compatibility-only/ignored`; they are not setup knobs. Unknown commands and
+malformed options point to the narrowest relevant help page.
 
 ## Daemon lifecycle
 
@@ -32,6 +64,9 @@ ours daemon restart
 CLI-owned PID record, the PID reported by the selected daemon, and its expected
 state directory/port. A daemon started by ours-mcp, a container, systemd, or any
 other launcher remains fully attachable, but these commands refuse to signal it.
+`start`, `serve`, and `restart` reject `--endpoint` because they must launch a
+locally selected daemon; this rejection happens before `restart` probes or stops
+anything.
 
 Selection is coherent and credential-safe. Use a single config file or select
 both the endpoint and its state directory:
@@ -66,9 +101,11 @@ secret mechanism or the existing SDK configuration, not CLI arguments.
 
 ## Operator commands
 
-All commands accept the selection flags `--config`, `--endpoint`, `--port`, and
-`--state-dir`; identity-scoped commands also accept `--identity NAME`, which
-binds that identity without force for the current process.
+Grouped operation commands accept the selection flags `--config`, `--endpoint`,
+`--port`, and `--state-dir`; identity-scoped commands also accept `--identity
+NAME`, which binds that identity without force for the current process. Run the
+specific command help for lifecycle/config applicability and compatibility-only
+flags.
 
 ```text
 identity     create | create-root | create-temporary | close-temporary
@@ -86,11 +123,17 @@ Input fields become kebab-case flags. For example:
 
 ```bash
 ours identity create --name BuildBot --bio "Build coordinator"
+ours profile set-bio --identity BuildBot --bio=        # clear the bio
+ours profile set-persona --identity BuildBot --persona= # clear the persona
 ours message send --identity BuildBot --contact Peer --text "done" --json
 ours file get --identity BuildBot --wire-ids ID1,ID2 --json
 ours conversation policy --identity Human --keep-history true
 ```
 
+An explicit file retrieval accepts 1–32 unique 64-hex wire IDs. `daemon watch`
+first binds its `--identity` without force, changing the CLI lease; it can fail
+with `BOUND_ELSEWHERE` when another live session holds that identity.
+
 Malformed JSON, unknown input fields, invalid booleans/integers, and incomplete
 file inputs fail closed before the request. Destructive identity/contact/invite
 operations require `--yes`.

package/dist/args.d.ts

@@ -7,6 +7,6 @@ export interface ParsedFlags {
     values: Record<string, string>;
     booleans: Set<string>;
 }
-export declare function parseFlags(argv: string[], valueFlags: ReadonlySet<string>, booleanFlags: ReadonlySet<string>): ParsedFlags;
+export declare function parseFlags(argv: string[], valueFlags: ReadonlySet<string>, booleanFlags: ReadonlySet<string>, emptyValueFlags?: ReadonlySet<string>): ParsedFlags;
 export declare function parseInteger(value: string, flag: string, min?: number, max?: number): number;
 export declare function parseBoolean(value: string, flag: string): boolean;

package/dist/args.js

@@ -3,7 +3,7 @@ import {
   parseBoolean,
   parseFlags,
   parseInteger
-} from "./chunk-AXXFFER2.js";
+} from "./chunk-6NFATG6P.js";
 export {
   CliUsageError,
   parseBoolean,

package/dist/{chunk-AXXFFER2.js → chunk-6NFATG6P.js}

@@ -6,7 +6,7 @@ var CliUsageError = class extends Error {
     this.name = "CliUsageError";
   }
 };
-function parseFlags(argv, valueFlags, booleanFlags) {
+function parseFlags(argv, valueFlags, booleanFlags, emptyValueFlags = /* @__PURE__ */ new Set()) {
   const positionals = [];
   const values = {};
   const booleans = /* @__PURE__ */ new Set();
@@ -35,7 +35,7 @@ function parseFlags(argv, valueFlags, booleanFlags) {
     }
     if (!valueFlags.has(name)) throw new CliUsageError(`unknown option: ${name}`);
     const value = equal >= 0 ? token.slice(equal + 1) : argv[++i];
-    if (value === void 0 || value === "") throw new CliUsageError(`${name} requires a value`);
+    if (value === void 0 || value === "" && !emptyValueFlags.has(name)) throw new CliUsageError(`${name} requires a value`);
     if (Object.prototype.hasOwnProperty.call(values, name)) throw new CliUsageError(`${name} may be given only once`);
     values[name] = value;
   }

package/dist/chunk-HNBWRI4O.js

@@ -0,0 +1,399 @@
+import {
+  fieldFlag,
+  isOperationName,
+  operationNames,
+  operationSpec
+} from "./chunk-QRNZFPNJ.js";
+import {
+  CliUsageError
+} from "./chunk-6NFATG6P.js";
+import {
+  COMMAND_GROUPS,
+  DESTRUCTIVE_OPERATIONS,
+  IDENTITY_PREBIND_EXCEPTIONS,
+  commandSpec,
+  isCommandGroup
+} from "./chunk-YSHMCQ2B.js";
+
+// src/help.ts
+var pad = (value, width = 32) => value.length >= width ? `${value} ` : value.padEnd(width);
+var option = (syntax, description) => `  ${pad(syntax)}${description}`;
+var heading = (name, body) => ["", `${name}:`, ...body];
+function operationSummary(spec) {
+  return spec.kind === "operation" ? operationSpec(spec.operation).summary : spec.summary;
+}
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function displayDefault(value) {
+  if (value === "") return "empty string";
+  return JSON.stringify(value);
+}
+function fieldType(field, context) {
+  if (field.values) return `Accepted values: ${field.values.join(", ")}.`;
+  if (field.kind === "boolean") return context === "json" ? "Use a JSON boolean (true or false)." : "Use true or false (1 and 0 are also accepted).";
+  if (field.kind === "integer") return field.positive ? "Use an integer of 1 or greater." : context === "json" ? "Use a safe integer." : "Use a non-negative integer.";
+  if (field.kind === "integer[]") return "Command flags use comma-separated integers; API JSON uses an integer array.";
+  if (field.kind === "string[]") return "Command flags use comma-separated values; API JSON uses a string array.";
+  return void 0;
+}
+function fieldDescription(field, name, defaults, context) {
+  const details = [field.help];
+  if (Object.prototype.hasOwnProperty.call(defaults, name)) details.push(`Default: ${displayDefault(defaults[name])}.`);
+  else if (field.required) details.push("Required.");
+  else details.push("Optional.");
+  const type = fieldType(field, context);
+  if (type) details.push(type);
+  return details.join(" ");
+}
+function operationFieldOptions(spec, defaults) {
+  return Object.entries(spec.fields).map(([name, field]) => option(`${fieldFlag(name)} ${field.valueName}`, fieldDescription(field, name, defaults, "flags")));
+}
+function apiFieldOptions(spec) {
+  const entries = Object.entries(spec.fields);
+  if (entries.length === 0) return [option("(none)", "Omit --input, or provide an empty JSON object.")];
+  return entries.map(([name, field]) => option(name, fieldDescription(field, name, {}, "json")));
+}
+function operationUsage(group, action, command) {
+  const spec = operationSpec(command.operation);
+  const fields = Object.entries(spec.fields).map(([name, field]) => {
+    const flag = `${fieldFlag(name)} ${field.valueName}`;
+    return field.required && !Object.prototype.hasOwnProperty.call(command.defaults ?? {}, name) ? flag : `[${flag}]`;
+  });
+  return [`ours ${group} ${action}`, ...fields, "[selection/output options]"].join(" ");
+}
+function cliExample(group, action, command) {
+  const spec = operationSpec(command.operation);
+  const args = [`ours ${group} ${action}`];
+  for (const [name, value] of Object.entries(spec.exampleInput ?? {})) {
+    if (Object.prototype.hasOwnProperty.call(command.defaults ?? {}, name) && command.defaults?.[name] === value) continue;
+    const rendered = Array.isArray(value) ? value.join(",") : String(value);
+    args.push(fieldFlag(name), shellQuote(rendered));
+  }
+  if (["profile", "invite", "contact", "message", "file", "conversation"].includes(group) && command.operation !== "list-local-contact-book") {
+    args.push("--identity", "BuildBot");
+  }
+  if (group === "identity" && ["show", "release"].includes(action)) args.push("--identity", "BuildBot");
+  if (DESTRUCTIVE_OPERATIONS.has(command.operation)) args.push("--yes");
+  args.push("--json");
+  return args.join(" ");
+}
+function commonOperationOptions(operation, fieldFlags) {
+  const out = [
+    option("--endpoint URL", "Connect to this running daemon URL; pair it with the matching --state-dir."),
+    option("--port N", "Select daemon port 1\u201365535."),
+    option("--state-dir PATH", "Select the daemon state directory used for endpoint identity verification."),
+    option("--config PATH", "Read daemon selection and credentials from this config file.")
+  ];
+  if (!fieldFlags.has("--identity")) {
+    out.push(option("--identity NAME", IDENTITY_PREBIND_EXCEPTIONS.has(operation) ? "Compatibility-only/ignored for this operation; use the operation\u2019s --name option instead." : "Bind this identity without force before invoking the operation."));
+  }
+  out.push(
+    option("--json", operation === "watch-notifications" ? "Compatibility-only: watch always streams JSON Lines (one event per line); errors remain on stderr as JSON." : "Write one JSON value to stdout; errors remain on stderr as JSON."),
+    option("--yes", DESTRUCTIVE_OPERATIONS.has(operation) ? "Required confirmation for this destructive operation." : "Compatibility-only/ignored for this non-destructive operation."),
+    option("--help", "Show this help and exit without connecting to a daemon.")
+  );
+  return out;
+}
+function nativeDaemonOptions(action) {
+  const lifecycle = /* @__PURE__ */ new Set(["serve", "start", "stop", "restart", "status"]);
+  const service = /* @__PURE__ */ new Set(["install-service", "uninstall-service"]);
+  const selected = lifecycle.has(action);
+  const install = action === "install-service";
+  const rows = [
+    ["--endpoint URL", selected ? action === "serve" || action === "start" || action === "restart" ? "Rejected: this action must start a local selected daemon." : "Select a running endpoint; pair it with --state-dir." : "Compatibility-only/ignored for service management."],
+    ["--port N", selected ? "Select daemon port 1\u201365535." : "Compatibility-only/ignored for service management."],
+    ["--state-dir PATH", selected ? "Select the daemon state directory." : "Compatibility-only/ignored for service management."],
+    ["--config PATH", selected ? "Use this daemon config for lifecycle selection." : action === "install-service" ? "Embed this config file\u2019s absolute path in the installed unit." : "Compatibility-only/ignored by uninstall-service."],
+    ["--identity NAME", "Compatibility-only/ignored by daemon lifecycle and service commands."],
+    ["--json", action === "serve" ? "Compatibility-only/ignored because serve runs until interrupted." : "Write one JSON result to stdout."],
+    ["--yes", service.has(action) ? "Confirm the service-manager change; not needed with --dry-run." : "Compatibility-only/ignored for this action."],
+    ["--managed", action === "serve" ? "Write the CLI-owned PID record after the foreground daemon starts." : "Compatibility-only/ignored for this action."],
+    ["--dry-run", service.has(action) ? "Return the planned service-manager changes without writing or running systemctl." : "Compatibility-only/ignored for this action."],
+    ["--force", install ? "Allow replacement of an existing user unit not marked as CLI-managed." : "Compatibility-only/ignored for this action."],
+    ["--help", "Show this help and exit without starting, stopping, probing, or installing anything."]
+  ];
+  return rows.map(([syntax, description]) => option(syntax, description));
+}
+function nativeConfigOptions(action) {
+  const show = action === "show";
+  const rows = [
+    ["--config PATH", show ? "Read and report this config file." : "Write this config file (default: $OURS_CONFIG or ~/.ours/config.json)."],
+    ["--endpoint URL", show ? "Resolve and report this endpoint selection." : "Compatibility-only/ignored by config setup."],
+    ["--port N", show ? "Resolve and report port 1\u201365535." : "Set daemon port 1\u201365535."],
+    ["--state-dir PATH", show ? "Resolve and report this state directory." : "Set the absolute daemon state directory."],
+    ["--identity NAME", "Compatibility-only/ignored by config commands."],
+    ["--broker-url URL", show ? "Compatibility-only/ignored by config show." : "Set the broker WebSocket URL."],
+    ["--gc-interval-ms N", show ? "Compatibility-only/ignored by config show." : "Set a positive garbage-collection interval in milliseconds."],
+    ["--auto-start true|false", show ? "Compatibility-only/ignored by config show." : "Set automatic daemon startup (1/0 are also accepted)."],
+    ["--api-visibility MODE", show ? "Compatibility-only/ignored by config show." : "Set owner, shared, or open API visibility."],
+    ["--dry-run", show ? "Compatibility-only/ignored by config show." : "Return the merged redacted result without writing the file."],
+    ["--json", "Write one JSON value to stdout."],
+    ["--help", "Show this help and exit without reading or writing configuration."]
+  ];
+  return rows.map(([syntax, description]) => option(syntax, description));
+}
+function renderNativeHelp(version, group, action, spec) {
+  const options = spec.kind === "daemon" ? nativeDaemonOptions(action) : nativeConfigOptions(action);
+  const usage = spec.kind === "daemon" ? `ours daemon ${action} [options]` : action === "setup" ? "ours config setup SETTING... [--dry-run] [--json]" : "ours config show [selection options] [--json]";
+  return [
+    `ours ${version} \u2014 ${group} ${action}`,
+    "",
+    spec.summary,
+    "",
+    `Usage: ${usage}`,
+    ...heading("Options", options),
+    ...heading("Behavior", [`  ${spec.effects}`]),
+    ...heading("Example", [`  ${spec.example}`]),
+    "",
+    `More help: ours help ${group}`,
+    ""
+  ].join("\n");
+}
+function renderOperationHelp(version, group, action, command) {
+  const spec = operationSpec(command.operation);
+  const defaults = command.defaults ?? {};
+  const fields = operationFieldOptions(spec, defaults);
+  const fieldFlags = new Set(Object.keys(spec.fields).map(fieldFlag));
+  const options = [...fields, ...commonOperationOptions(command.operation, fieldFlags)];
+  const behavior = [`  ${spec.effects}`];
+  if (group === "daemon" && command.operation === "watch-notifications") {
+    behavior.push("  Before streaming, --identity attempts a non-force bind that changes this CLI lease; it fails with BOUND_ELSEWHERE when another live session holds the identity.");
+  }
+  return [
+    `ours ${version} \u2014 ${group} ${action}`,
+    "",
+    spec.summary,
+    "",
+    `Usage: ${operationUsage(group, action, command)}`,
+    "",
+    "Positional arguments: none after the command name.",
+    ...heading("Options", options),
+    ...heading("Behavior", behavior),
+    ...heading("Example", [`  ${cliExample(group, action, command)}`]),
+    "",
+    `Expert equivalent: ours help api ${command.operation}`,
+    `More help: ours help ${group}`,
+    ""
+  ].join("\n");
+}
+function renderGroupHelp(version, group) {
+  const spec = COMMAND_GROUPS[group];
+  const commands = Object.entries(spec.commands).map(([name, command]) => option(name, operationSummary(command)));
+  const shared = group === "config" ? [
+    "Use `ours config <command> --help` or `ours help config <command>` for exact settings and compatibility-only flags."
+  ] : group === "daemon" ? [
+    "Use `ours daemon <command> --help` or `ours help daemon <command>` for exact lifecycle, service, selection, and compatibility-only flags."
+  ] : [
+    "Operation commands accept --endpoint, --port, --state-dir, --config, --identity, --json, --yes, and --help.",
+    "--yes is meaningful only where the specific help marks an operation destructive; otherwise it is compatibility-only/ignored."
+  ];
+  return [
+    `ours ${version} \u2014 ${group} commands`,
+    "",
+    spec.summary,
+    "",
+    `Usage: ours ${group} <command> [options]`,
+    `       ours help ${group} <command>`,
+    ...heading("Commands", commands),
+    ...heading("Discovery", shared.map((line) => `  ${line}`)),
+    ...heading("Example", [`  ours help ${group} ${Object.keys(spec.commands)[0]}`]),
+    ""
+  ].join("\n");
+}
+function apiExample(operation, spec) {
+  const args = [`ours api ${operation}`];
+  if (Object.keys(spec.fields).length > 0) args.push("--input", shellQuote(JSON.stringify(spec.exampleInput ?? {})));
+  const noBindNeeded = /* @__PURE__ */ new Set([
+    "create-identity",
+    "create-temporary-identity",
+    "create-root-identity",
+    "define-local-identity-file",
+    "choose-identity",
+    "list-identities",
+    "remove-identity",
+    "version",
+    "state-dir",
+    "identities",
+    "unread",
+    "watch-notifications",
+    "list-local-contact-book"
+  ]);
+  if (!noBindNeeded.has(operation)) args.push("--identity", "BuildBot");
+  if (DESTRUCTIVE_OPERATIONS.has(operation)) args.push("--yes");
+  args.push("--json");
+  return args.join(" ");
+}
+function renderApiOperationHelp(version, operation) {
+  const spec = operationSpec(operation);
+  const options = [
+    option("--input JSON", "Operation input as one JSON object."),
+    option("--input-file PATH", "Read the JSON object from PATH, or use - for stdin. Mutually exclusive with --input."),
+    ...commonOperationOptions(operation, /* @__PURE__ */ new Set())
+  ];
+  return [
+    `ours ${version} \u2014 api ${operation}`,
+    "",
+    spec.summary,
+    "",
+    `Usage: ours api ${operation} [--input JSON | --input-file PATH] [selection/output options]`,
+    "",
+    "Positional arguments: exactly one allowlisted operation name after `api`.",
+    ...heading("JSON fields", apiFieldOptions(spec)),
+    ...heading("Options", options),
+    ...heading("Behavior", [`  ${spec.effects}`, "  Unknown JSON fields and invalid types fail before the operation is invoked."]),
+    ...heading("Example", [`  ${apiExample(operation, spec)}`]),
+    "",
+    "List all expert operations: ours api list",
+    ""
+  ].join("\n");
+}
+function renderApiListHelp(version) {
+  return [
+    `ours ${version} \u2014 api list`,
+    "",
+    "List every expert operation accepted by `ours api` in deterministic order.",
+    "",
+    "Usage: ours api list [--json] [--help]",
+    ...heading("Options", [
+      option("--json", "Write the operation names as one JSON array instead of text."),
+      option("--help", "Show this help without connecting to a daemon.")
+    ]),
+    ...heading("Behavior", ["  Read-only and local: this command does not connect to a daemon."]),
+    ...heading("Examples", ["  ours api list", "  ours api list --json"]),
+    ""
+  ].join("\n");
+}
+function renderApiHelp(version) {
+  const operations = operationNames().map((name) => option(name, operationSpec(name).summary));
+  return [
+    `ours ${version} \u2014 expert API operations`,
+    "",
+    "Invoke the CLI\u2019s explicit OursClient allowlist with a typed JSON object. Grouped commands are easier for routine operator work.",
+    "",
+    "Usage: ours api list [--json]",
+    "       ours api <operation> [--input JSON | --input-file PATH] [options]",
+    "       ours help api <operation>",
+    ...heading("Operations", operations),
+    ...heading("Input", [
+      option("--input JSON", "Inline JSON object; quote it so the shell passes one argument."),
+      option("--input-file PATH", "Read JSON from a file, or use - for stdin. Mutually exclusive with --input."),
+      option("--json", "For `api list`, return the operation-name array as JSON."),
+      option("--help", "Show help without connecting to a daemon.")
+    ]),
+    ...heading("Examples", [
+      "  ours api list --json",
+      "  ours help api send-message"
+    ]),
+    ""
+  ].join("\n");
+}
+function renderVersionHelp(version) {
+  return [
+    `ours ${version} \u2014 CLI version`,
+    "",
+    "Show the installed @ours.network/cli package version.",
+    "",
+    "Usage: ours version [--json] [--help]",
+    ...heading("Options", [
+      option("--json", 'Write {"name":"@ours.network/cli","version":"\u2026"} to stdout.'),
+      option("--help", "Show this help.")
+    ]),
+    ...heading("Compatibility", ["  Additional tokens are currently ignored; they are not setup knobs and should not be relied on."]),
+    ...heading("Example", ["  ours version --json"]),
+    ""
+  ].join("\n");
+}
+function renderTopHelp(version) {
+  const groups = Object.entries(COMMAND_GROUPS).map(([name, spec]) => option(name, spec.summary));
+  return [
+    `ours ${version} \u2014 operator CLI for the shared ours daemon`,
+    "",
+    "Create and manage identities, encrypted contacts/messages/files, and daemon lifecycle through the transport-neutral @ours.network/sdk client.",
+    "",
+    "Usage: ours <command> [options]",
+    "       ours help [command [subcommand]]",
+    "       ours <command> [subcommand] --help",
+    ...heading("First-time setup", [
+      "  1. Install Node.js 20 or newer and `npm install --global @ours.network/cli`.",
+      "  2. Inspect redacted defaults with `ours config show --json`.",
+      '  3. Configure safe daemon settings, for example `ours config setup --port 3070 --state-dir "$HOME/.ours/state"`.',
+      "  4. Start and verify the shared daemon with `ours daemon start` and `ours daemon status --json`.",
+      "  5. Create the Human identity first: `ours identity create-root --name Alice@laptop`.",
+      '  6. Add agent roles with `ours identity create --name BuildBot --bio "Build coordinator"`.'
+    ]),
+    ...heading("Commands", [
+      ...groups,
+      option("api", "Invoke the expert operation allowlist with typed JSON input."),
+      option("version", "Show the installed CLI version."),
+      option("help", "Show top-level, group, command, or API-operation help.")
+    ]),
+    ...heading("Connection and configuration", [
+      "  Selection flags are --config PATH, or a coherent --endpoint URL / --port N / --state-dir PATH selection.",
+      "  The default config is $OURS_CONFIG when set, otherwise ~/.ours/config.json when present.",
+      "  Pair an explicit endpoint with its matching state directory; the CLI verifies /state-dir before sending a discovered API token.",
+      "  There is intentionally no token flag. Keep credentials in operator-owned environment/config secret handling."
+    ]),
+    ...heading("Output and exit status", [
+      "  Results go to stdout; diagnostics go to stderr. --json writes one JSON value and JSON-formatted errors, except watch streams JSON Lines.",
+      "  Exit 0 means success, 2 means command/option usage error, and 1 means another failure.",
+      "  `ours daemon status` uses exit 3 when the selected daemon is stopped.",
+      "  Help is plain text, exits 0, and performs no daemon, file, or service-manager action."
+    ]),
+    ...heading("Examples", [
+      "  ours help identity create",
+      '  ours message send --identity BuildBot --contact Peer --text "Build finished." --json',
+      "  ours file list --identity BuildBot --json",
+      "  ours api list --json"
+    ]),
+    "",
+    "Run `ours help <command>` to see its commands, then `ours help <command> <subcommand>` for every accepted option and side effect.",
+    ""
+  ].join("\n");
+}
+function helpRequestPath(argv) {
+  if (argv.length === 0) return [];
+  if (argv[0] === "help") return argv.slice(1).filter((value) => value !== "--help");
+  if (argv.includes("--help")) {
+    if (argv[0].startsWith("--")) return [];
+    const path = [argv[0]];
+    if ((isCommandGroup(argv[0]) || argv[0] === "api") && argv[1] !== void 0 && !argv[1].startsWith("--")) path.push(argv[1]);
+    return path;
+  }
+  if (argv.length === 1 && (isCommandGroup(argv[0]) || argv[0] === "api")) return [argv[0]];
+  return null;
+}
+function renderHelp(path, version) {
+  if (path.length === 0 || path.length === 1 && path[0] === "help") return renderTopHelp(version);
+  if (path.length === 1 && path[0] === "api") return renderApiHelp(version);
+  if (path.length === 1 && path[0] === "version") return renderVersionHelp(version);
+  if (path[0] === "api") {
+    if (path.length === 2 && path[1] === "list") return renderApiListHelp(version);
+    if (path.length !== 2 || !isOperationName(path[1])) {
+      throw new CliUsageError(`unknown API help topic ${JSON.stringify(path.slice(1).join(" "))}; run \`ours help api\``);
+    }
+    return renderApiOperationHelp(version, path[1]);
+  }
+  if (!isCommandGroup(path[0])) throw new CliUsageError(`unknown help topic ${JSON.stringify(path.join(" "))}; run \`ours help\``);
+  if (path.length === 1) return renderGroupHelp(version, path[0]);
+  if (path.length !== 2) throw new CliUsageError(`too many help topics; run \`ours help ${path[0]}\``);
+  const spec = commandSpec(path[0], path[1]);
+  if (!spec) throw new CliUsageError(`unknown ${path[0]} help topic ${JSON.stringify(path[1])}; run \`ours help ${path[0]}\``);
+  return spec.kind === "operation" ? renderOperationHelp(version, path[0], path[1], spec) : renderNativeHelp(version, path[0], path[1], spec);
+}
+function helpHint(group, action) {
+  if (group && isCommandGroup(group)) {
+    if (action && commandSpec(group, action)) return `Run \`ours help ${group} ${action}\` for usage.`;
+    return `Run \`ours help ${group}\` to list valid commands.`;
+  }
+  if (group === "api") return action === "list" ? "Run `ours help api list` for usage." : action && isOperationName(action) ? `Run \`ours help api ${action}\` for usage.` : "Run `ours help api` to list valid operations.";
+  return "Run `ours help` to list commands.";
+}
+
+export {
+  renderTopHelp,
+  helpRequestPath,
+  renderHelp,
+  helpHint
+};