not-manage 0.2.2 → 0.2.3

package/src/cli.js

@@ -3,20 +3,111 @@ const {
   authRevoke,
   authSetup,
   authStatus,
-  maybeRunSetupOnFirstUse,
   setupWizard,
   whoAmI,
 } = require("./commands-auth");
-const { hasFlag, parseOptions, readBooleanOption, readCommandOptions } = require("./cli-options");
+const { readJsonInput } = require("./agent-input");
+const { UsageError } = require("./cli-errors");
+const {
+  hasFlag,
+  parseOptions,
+  readBooleanOption,
+  readCommandOptions,
+  readStringOption,
+} = require("./cli-options");
+const { agentContext } = require("./commands-agent-context");
+const { doctor } = require("./commands-doctor");
+const { rawRequest } = require("./commands-request");
 const { getResourceHandler } = require("./resource-handlers");
 const {
   RESOURCE_ORDER,
+  findMissingRequiredOptions,
   getResourceMetadata,
   listRequiredOptionFlags,
   normalizeResourceCommand,
 } = require("./resource-metadata");
 const { version } = require("../package.json");
 
+const HELP_FLAGS = new Set(["-h", "--help"]);
+const VERSION_FLAGS = new Set(["-v", "--version"]);
+const GLOBAL_BOOLEAN_FLAGS = new Set([
+  "agent",
+  "compact",
+  "json",
+  "no-color",
+  "no-input",
+  "yes",
+  "force",
+]);
+
+function parseGlobalBoolean(value, flagName) {
+  if (value === undefined || value === "") {
+    return true;
+  }
+
+  const normalized = String(value).trim().toLowerCase();
+  if (normalized === "true") {
+    return true;
+  }
+  if (normalized === "false") {
+    return false;
+  }
+
+  throw new UsageError(`\`--${flagName}\` must be \`true\` or \`false\`.`, {
+    code: "invalid_global_flag",
+  });
+}
+
+function readGlobalFlags(args) {
+  const values = {
+    agent: false,
+    compact: false,
+    force: false,
+    json: false,
+    noColor: false,
+    noInput: false,
+    yes: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith("--")) {
+      continue;
+    }
+
+    const [flagName, inlineValue] = token.slice(2).split("=", 2);
+    if (!GLOBAL_BOOLEAN_FLAGS.has(flagName)) {
+      continue;
+    }
+
+    let value = inlineValue;
+    const next = args[index + 1];
+    if (
+      value === undefined &&
+      (next === "true" || next === "false")
+    ) {
+      value = next;
+      index += 1;
+    }
+
+    values[flagName.replace(/-([a-z])/g, (_match, char) => char.toUpperCase())] =
+      parseGlobalBoolean(value, flagName);
+  }
+
+  if (values.agent) {
+    values.compact = true;
+    values.json = true;
+    values.noColor = true;
+    values.noInput = true;
+    values.yes = true;
+  }
+  if (values.force) {
+    values.yes = true;
+  }
+
+  return values;
+}
+
 function maybePrintDefaultFields(command, sub, optionValues) {
   if (optionValues.fields !== true) {
     return false;
@@ -24,8 +115,12 @@ function maybePrintDefaultFields(command, sub, optionValues) {
 
   const defaults = getResourceMetadata(command)?.defaultFields?.[sub];
   if (!defaults) {
-    throw new Error(
-      "`--fields` requires a comma-separated value for this command. Example: --fields id,name"
+    throw new UsageError(
+      "`--fields` requires a comma-separated value for this command. Example: --fields id,name",
+      {
+        code: "missing_fields_value",
+        hint: "--fields id,name",
+      }
     );
   }
 
@@ -74,85 +169,693 @@ function warnAboutRedaction(resourceMetadata, sub, optionValues, redacted) {
   }
 }
 
-function printHelp() {
+function printOptionLines(entries = []) {
+  if (entries.length === 0) {
+    return;
+  }
+
+  console.log("Options:");
+  entries.forEach((entry) => {
+    if (typeof entry === "string") {
+      console.log(`  ${entry}`);
+      return;
+    }
+
+    console.log(`  ${entry.usage.padEnd(28, " ")} ${entry.description}`);
+  });
+}
+
+function printExamples(examples = []) {
+  if (examples.length === 0) {
+    return;
+  }
+
+  console.log("Examples:");
+  examples.forEach((example) => {
+    console.log(`  ${example}`);
+  });
+}
+
+function printCommandHelp(title, details = {}) {
+  const {
+    description,
+    examples = [],
+    notes = [],
+    options = [],
+    usage = [],
+  } = details;
+
+  console.log(title);
+  console.log("");
+
+  if (usage.length > 0) {
+    console.log("Usage:");
+    usage.forEach((line) => {
+      console.log(`  ${line}`);
+    });
+    console.log("");
+  }
+
+  if (description) {
+    console.log("Description:");
+    console.log(`  ${description}`);
+    console.log("");
+  }
+
+  if (notes.length > 0) {
+    console.log("Notes:");
+    notes.forEach((line) => {
+      console.log(`  ${line}`);
+    });
+    console.log("");
+  }
+
+  printOptionLines(options);
+  if (options.length > 0 && examples.length > 0) {
+    console.log("");
+  }
+  printExamples(examples);
+}
+
+function optionPlaceholder(optionDef) {
+  switch (optionDef.kind) {
+    case "boolean":
+      return " <true|false>";
+    case "object":
+      return " <json|key=value>";
+    case "string-array":
+      return " <value[,value]>";
+    default:
+      return " <value>";
+  }
+}
+
+function formatResourceOption(optionDef) {
+  if (optionDef.positional !== undefined) {
+    return null;
+  }
+
+  return `--${optionDef.option}${optionDef.kind === "flag" ? "" : optionPlaceholder(optionDef)}`;
+}
+
+function buildResourceOptionLines(resourceMetadata, sub) {
+  const optionLines = Object.values(resourceMetadata.optionSchema?.[sub] || {})
+    .map((optionDef) => formatResourceOption(optionDef))
+    .filter(Boolean);
+
+  if (sub === "list" || sub === "get") {
+    optionLines.push("--options-file <path|->");
+    optionLines.push("--json");
+    optionLines.push("--compact");
+    optionLines.push("--redacted");
+    optionLines.push("--unredacted");
+  }
+
+  if (sub === "get") {
+    optionLines.push("--ids-file <path|->");
+    optionLines.push("--stdin");
+  }
+
+  optionLines.push("-h, --help");
+  return optionLines;
+}
+
+function buildResourceExamples(command, sub, requiredFlags) {
+  if (sub === "get") {
+    return [
+      `not-manage ${command} get 123 --json`,
+      `not-manage ${command} get 123 --fields id,name --json`,
+      `printf "123\\n456\\n" | not-manage ${command} get --stdin --json`,
+    ];
+  }
+
+  const exampleValues = {
+    "--conversation-id": "123",
+    "--matter-id": "123",
+    "--type": "Matter",
+    "--user-id": "123",
+  };
+  const requiredExample =
+    requiredFlags.length > 0
+      ? `${requiredFlags.map((flag) => `${flag} <value>`).join(" ")} `
+      : "";
+  const realisticRequiredExample =
+    requiredFlags.length > 0
+      ? `${requiredFlags.map((flag) => `${flag} ${exampleValues[flag] || "123"}`).join(" ")} `
+      : "";
+
+  return [
+    `not-manage ${command} list ${realisticRequiredExample}--json`,
+    `not-manage ${command} list ${requiredExample}--fields id,name`,
+    `not-manage ${command} list --options-file filters.json --json`,
+  ];
+}
+
+function printGlobalHelp() {
   console.log("not-manage");
   console.log("");
   console.log("Usage:");
   console.log("  not-manage <command> [options]");
   console.log("");
   console.log("Commands:");
-  console.log("  setup              Run guided setup and OAuth login");
-  console.log("  auth setup         Configure client credentials in OS keychain");
-  console.log("  auth login         Run local OAuth login flow");
-  console.log("  auth status        Show auth status and connected user");
-  console.log("  auth revoke        Revoke token and clear local token storage");
-
-  RESOURCE_ORDER.forEach((command) => {
-    const resourceMetadata = getResourceMetadata(command);
-    ["list", "get"].forEach((sub) => {
-      if (!resourceMetadata.capabilities[sub].enabled) {
-        return;
-      }
-
-      const usage = `${command} ${sub}`.padEnd(18, " ");
-      const requiredFlags = listRequiredOptionFlags(resourceMetadata, sub);
-      const requirementNote =
-        requiredFlags.length > 0 ? ` (requires ${requiredFlags.join(", ")})` : "";
-      console.log(`  ${usage} ${resourceMetadata.help[sub]}${requirementNote}`);
-    });
-  });
-
+  console.log("  setup              Guided setup plus OAuth login");
+  console.log("  doctor             Diagnose config, token, and Clio connectivity");
+  console.log("  agent-context      Machine-readable command/resource catalog");
+  console.log("  auth               Manage app credentials and OAuth tokens");
   console.log("  whoami             Call /api/v4/users/who_am_i");
+  console.log("  request            Raw API escape hatch with write guard");
+  console.log("  <resource>         Read Clio resources with list/get subcommands");
   console.log("");
-  console.log("Aliases:");
-  console.log("  Singular aliases are accepted, for example:");
-  console.log("  contact get, matter get, bill get, invoice get, task get, user get");
+  console.log("Resources:");
+  console.log("  Run `not-manage agent-context` for the full machine-readable catalog.");
+  console.log("  Run `not-manage <resource> --help` for resource subcommands.");
+  console.log("  Singular aliases are accepted, for example `contact get` and `matter get`.");
   console.log("");
   console.log("Options:");
+  console.log("  --agent            Agent defaults: --json --compact --no-input --no-color --yes");
+  console.log("  --compact          Return reduced JSON fields for lower-token output");
   console.log("  --fields <list>    Override returned fields; pass `--fields` alone to print defaults");
   console.log("  --json             Print machine-readable JSON for supported commands");
+  console.log("  --no-input         Disable interactive prompts where supported");
+  console.log("  --no-color         Disable colored output");
+  console.log("  --force            Alias for --yes");
   console.log("  --redacted         Kept for compatibility; data commands are redacted by default");
   console.log("  --unredacted       Show raw output without default redaction");
   console.log("  -h, --help         Show help");
   console.log("  -v, --version      Show version");
+  console.log("");
+  console.log("Examples:");
+  console.log("  not-manage --agent agent-context");
+  console.log("  not-manage --agent doctor");
+  console.log("  not-manage --agent contacts list --limit 5");
+  console.log("");
+  console.log("Run `not-manage <command> --help` for command-specific flags and examples.");
 }
 
-function buildResourceOptions(resourceMetadata, sub, optionValues, positional, json, redacted) {
+function printSetupHelp() {
+  printCommandHelp("not-manage setup", {
+    description: "Run guided credential setup, then continue directly into OAuth login.",
+    usage: ["not-manage setup [auth-setup-options]"],
+    notes: [
+      "This command accepts the same setup flags as `not-manage auth setup`.",
+      "If required values are missing, prompts are used only in an interactive terminal.",
+    ],
+    options: [
+      { usage: "--confirm-confidentiality", description: "Acknowledge the confidentiality warning without a prompt" },
+      { usage: "--region <code>", description: "Clio region code: us, ca, eu, or au" },
+      { usage: "--client-id <value>", description: "App Key / Client ID" },
+      { usage: "--client-secret <value>", description: "App Secret / Client Secret" },
+      { usage: "--redirect-uri <url>", description: "Override the loopback OAuth redirect URI" },
+      { usage: "--open-browser <true|false>", description: "Open the regional developer portal during setup" },
+      { usage: "-h, --help", description: "Show help" },
+    ],
+    examples: [
+      "not-manage setup",
+      "not-manage setup --confirm-confidentiality --region us --client-id <key> --client-secret <secret>",
+    ],
+  });
+}
+
+function printAuthHelp() {
+  printCommandHelp("not-manage auth", {
+    description: "Manage Clio app credentials and OAuth tokens.",
+    usage: ["not-manage auth <subcommand> [options]"],
+    notes: [
+      "Subcommands: setup, login, status, revoke",
+      "Run `not-manage auth <subcommand> --help` for flags and examples.",
+    ],
+    examples: [
+      "not-manage auth setup --help",
+      "not-manage auth status --json",
+      "not-manage auth revoke --dry-run",
+    ],
+  });
+}
+
+function printAuthSetupHelp() {
+  printCommandHelp("not-manage auth setup", {
+    description: "Configure client credentials in the OS keychain.",
+    usage: ["not-manage auth setup [options]"],
+    notes: [
+      "If required values are missing, prompts are used only in an interactive terminal.",
+      "Outside a TTY, pass `--confirm-confidentiality`, `--client-id`, and `--client-secret`.",
+    ],
+    options: [
+      { usage: "--confirm-confidentiality", description: "Acknowledge the confidentiality warning without a prompt" },
+      { usage: "--region <code>", description: "Clio region code: us, ca, eu, or au" },
+      { usage: "--client-id <value>", description: "App Key / Client ID" },
+      { usage: "--client-secret <value>", description: "App Secret / Client Secret" },
+      { usage: "--redirect-uri <url>", description: "Override the loopback OAuth redirect URI" },
+      { usage: "--open-browser <true|false>", description: "Open the regional developer portal during setup" },
+      { usage: "-h, --help", description: "Show help" },
+    ],
+    examples: [
+      "not-manage auth setup",
+      "not-manage auth setup --confirm-confidentiality --region us --client-id <key> --client-secret <secret>",
+    ],
+  });
+}
+
+function printAuthLoginHelp() {
+  printCommandHelp("not-manage auth login", {
+    description: "Run the local OAuth login flow using the saved client credentials.",
+    usage: ["not-manage auth login"],
+    options: [{ usage: "-h, --help", description: "Show help" }],
+    examples: ["not-manage auth login"],
+  });
+}
+
+function printAuthStatusHelp() {
+  printCommandHelp("not-manage auth status", {
+    description: "Show the configured region, token source, and connected user.",
+    usage: ["not-manage auth status [options]"],
+    options: [
+      { usage: "--json", description: "Print machine-readable JSON" },
+      { usage: "--unredacted", description: "Show raw connected-user details instead of masked values" },
+      { usage: "-h, --help", description: "Show help" },
+    ],
+    examples: ["not-manage auth status", "not-manage auth status --json"],
+  });
+}
+
+function printDoctorHelp() {
+  printCommandHelp("not-manage doctor", {
+    description:
+      "Report CLI version, config source, region/host, and token/auth state. Works without auth so agents can diagnose missing setup without triggering other errors.",
+    usage: ["not-manage doctor [options]"],
+    options: [
+      { usage: "--json", description: "Print machine-readable JSON" },
+      { usage: "--compact", description: "Print compact JSON when combined with --json" },
+      { usage: "--fail-on <warn|error>", description: "Exit non-zero when the report reaches this severity" },
+      { usage: "-h, --help", description: "Show help" },
+    ],
+    examples: ["not-manage doctor", "not-manage doctor --json", "not-manage doctor --fail-on warn"],
+  });
+}
+
+function printAgentContextHelp() {
+  printCommandHelp("not-manage agent-context", {
+    description: "Emit a machine-readable command and option map for agents.",
+    usage: ["not-manage agent-context [options]"],
+    options: [
+      { usage: "--compact", description: "Print compact JSON" },
+      { usage: "-h, --help", description: "Show help" },
+    ],
+    examples: ["not-manage agent-context", "not-manage --agent agent-context"],
+  });
+}
+
+function printRequestHelp() {
+  printCommandHelp("not-manage request", {
+    description:
+      "Raw Clio API escape hatch. Reuses saved auth, base URL trust checks, redaction, and JSON envelope.",
+    usage: ["not-manage request <method> <path> [options]"],
+    notes: [
+      "Reads are safe by default: only GET and HEAD run without an extra confirmation flag.",
+      "Non-idempotent methods (POST/PUT/PATCH/DELETE) require `--write` and are treated as live writes.",
+      "`--dry-run` previews the validated request plan without sending it.",
+      "Paths are validated against the configured region host before the bearer token is sent.",
+      "Response bodies are redacted by default; pass `--unredacted` to inspect raw output.",
+    ],
+    options: [
+      { usage: "--query <k=v[,k=v]>", description: "Appended as URL query parameters" },
+      { usage: "--body-file <path|->", description: "JSON body file, or `-` to read from stdin" },
+      { usage: "--write", description: "Required for POST, PUT, PATCH, DELETE" },
+      { usage: "--dry-run", description: "Print the validated request plan without sending it" },
+      { usage: "--json", description: "Print machine-readable JSON (default for this command)" },
+      { usage: "--unredacted", description: "Show raw output without redaction" },
+      { usage: "-h, --help", description: "Show help" },
+    ],
+    examples: [
+      "not-manage request get /api/v4/users/who_am_i --json",
+      "not-manage request get /api/v4/matters.json --query status=open,limit=5 --json",
+      "not-manage request post /api/v4/activities.json --body-file body.json --dry-run --json",
+      "cat body.json | not-manage request post /api/v4/activities.json --body-file - --write --json",
+    ],
+  });
+}
+
+function printAuthRevokeHelp() {
+  printCommandHelp("not-manage auth revoke", {
+    description: "Revoke the current Clio token and clear the local keychain token.",
+    usage: ["not-manage auth revoke [options]"],
+    notes: ["Use `--dry-run` to inspect the action without changing remote or local state."],
+    options: [
+      { usage: "--yes", description: "Skip the confirmation prompt and revoke immediately" },
+      { usage: "--force", description: "Alias for --yes" },
+      { usage: "--dry-run", description: "Print the revoke plan without revoking or clearing tokens" },
+      { usage: "-h, --help", description: "Show help" },
+    ],
+    examples: ["not-manage auth revoke --dry-run", "not-manage auth revoke --yes"],
+  });
+}
+
+function printWhoAmIHelp() {
+  printCommandHelp("not-manage whoami", {
+    description: "Call `/api/v4/users/who_am_i` for the authenticated user.",
+    usage: ["not-manage whoami [options]"],
+    options: [
+      { usage: "--json", description: "Print machine-readable JSON" },
+      { usage: "-h, --help", description: "Show help" },
+    ],
+    examples: ["not-manage whoami", "not-manage whoami --json"],
+  });
+}
+
+function printResourceOverview(command, resourceMetadata) {
+  const subcommands = ["list", "get"].filter((sub) => resourceMetadata.capabilities[sub].enabled);
+
+  printCommandHelp(`not-manage ${command}`, {
+    description: `Explore the ${command} command surface.`,
+    usage: [`not-manage ${command} <subcommand> [options]`],
+    notes: [
+      `Subcommands: ${subcommands.join(", ")}`,
+      resourceMetadata.aliases.length > 0
+        ? `Aliases: ${resourceMetadata.aliases.join(", ")}`
+        : null,
+      `Run \`not-manage ${command} <subcommand> --help\` for flags and examples.`,
+    ].filter(Boolean),
+    examples: [
+      `not-manage ${command} list --help`,
+      resourceMetadata.capabilities.list.enabled ? `not-manage ${command} list --json` : null,
+      resourceMetadata.capabilities.get.enabled ? `not-manage ${command} get <id> --json` : null,
+    ].filter(Boolean),
+  });
+}
+
+function printResourceCommandHelp(command, sub, resourceMetadata) {
+  const requiredFlags = listRequiredOptionFlags(resourceMetadata, sub);
+  const usage =
+    sub === "get"
+      ? [`not-manage ${command} get <id> [options]`]
+      : [`not-manage ${command} list [options]`];
+  const notes = [];
+
+  if (requiredFlags.length > 0) {
+    notes.push(`Required filters: ${requiredFlags.join(", ")}`);
+  }
+
+  if (resourceMetadata.aliases.length > 0) {
+    notes.push(`Aliases: ${resourceMetadata.aliases.join(", ")}`);
+  }
+
+  printCommandHelp(`not-manage ${command} ${sub}`, {
+    description: resourceMetadata.help[sub],
+    usage,
+    notes,
+    options: buildResourceOptionLines(resourceMetadata, sub),
+    examples: buildResourceExamples(command, sub, requiredFlags),
+  });
+}
+
+function printCommandSpecificHelp(command, sub) {
+  if (!command) {
+    printGlobalHelp();
+    return;
+  }
+
+  if (command === "setup") {
+    printSetupHelp();
+    return;
+  }
+
+  if (command === "auth") {
+    if (!sub) {
+      printAuthHelp();
+      return;
+    }
+
+    if (sub === "setup") {
+      printAuthSetupHelp();
+      return;
+    }
+
+    if (sub === "login") {
+      printAuthLoginHelp();
+      return;
+    }
+
+    if (sub === "status") {
+      printAuthStatusHelp();
+      return;
+    }
+
+    if (sub === "revoke") {
+      printAuthRevokeHelp();
+      return;
+    }
+
+    throw new UsageError(
+      `Unknown subcommand for auth: ${sub}\nRun \`not-manage auth --help\`.`,
+      { code: "unknown_subcommand", hint: "not-manage auth --help" }
+    );
+  }
+
+  if (command === "whoami") {
+    printWhoAmIHelp();
+    return;
+  }
+
+  if (command === "doctor") {
+    printDoctorHelp();
+    return;
+  }
+
+  if (command === "agent-context") {
+    printAgentContextHelp();
+    return;
+  }
+
+  if (command === "request") {
+    printRequestHelp();
+    return;
+  }
+
+  const resourceMetadata = getResourceMetadata(command);
+  if (!resourceMetadata) {
+    throw new UsageError(
+      `Unknown command: ${command}\nRun \`not-manage --help\`.`,
+      { code: "unknown_command", hint: "not-manage --help" }
+    );
+  }
+
+  if (!sub) {
+    printResourceOverview(command, resourceMetadata);
+    return;
+  }
+
+  if (!resourceMetadata.capabilities[sub]?.enabled) {
+    throw new UsageError(
+      `Unknown subcommand for ${command}: ${sub}\nRun \`not-manage ${command} --help\`.`,
+      { code: "unknown_subcommand", hint: `not-manage ${command} --help` }
+    );
+  }
+
+  printResourceCommandHelp(command, sub, resourceMetadata);
+}
+
+function stripRoutingFlags(args) {
+  const routingArgs = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (HELP_FLAGS.has(arg) || VERSION_FLAGS.has(arg)) {
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      const [flagName, inlineValue] = arg.slice(2).split("=", 2);
+      if (GLOBAL_BOOLEAN_FLAGS.has(flagName)) {
+        const next = args[index + 1];
+        if (inlineValue === undefined && (next === "true" || next === "false")) {
+          index += 1;
+        }
+        continue;
+      }
+    }
+
+    routingArgs.push(arg);
+  }
+
+  return routingArgs;
+}
+
+function buildResourceOptions(
+  resourceMetadata,
+  sub,
+  optionValues,
+  positional,
+  json,
+  redacted,
+  compact
+) {
+  const baseOptions = {
+    json,
+    redacted,
+  };
+  if (compact) {
+    baseOptions.compact = true;
+  }
+
   return readCommandOptions(
     optionValues,
     resourceMetadata.optionSchema[sub],
     positional,
-    {
-      json,
-      redacted,
-    },
+    baseOptions,
     resourceMetadata.fixedOptions?.[sub]
   );
 }
 
-async function run(args) {
-  if (!args.length) {
-    const startedOnboarding = await maybeRunSetupOnFirstUse();
-    if (!startedOnboarding) {
-      printHelp();
-    }
+function assertRequiredResourceOptions(command, sub, resourceMetadata, options) {
+  const missing = findMissingRequiredOptions(resourceMetadata, sub, options);
+  if (missing.length === 0) {
     return;
   }
 
-  if (hasFlag(args, "-h", "--help")) {
-    printHelp();
+  const missingList = missing.join(", ");
+  const exampleFlags = missing.map((flag) => `${flag} <value>`).join(" ");
+  const message = [
+    `Missing required ${missing.length === 1 ? "flag" : "flags"} for \`not-manage ${command} ${sub}\`: ${missingList}.`,
+    `Usage: not-manage ${command} ${sub} ${exampleFlags}`.trim(),
+    `Run \`not-manage ${command} ${sub} --help\` for the full flag list.`,
+  ].join("\n");
+
+  throw new UsageError(message, {
+    code: "missing_required_flags",
+    hint: `not-manage ${command} ${sub} --help`,
+    details: { command, subcommand: sub, missing_flags: missing },
+  });
+}
+
+function assertResourceIdOption(command, sub, options) {
+  if (sub !== "get" || options.id || options.idsFile) {
     return;
   }
 
-  if (hasFlag(args, "-v", "--version")) {
-    console.log(`not-manage v${version}`);
+  const usage = `Usage: not-manage ${command} get <id>`;
+  throw new UsageError(usage, {
+    code: "missing_resource_id",
+    hint: `not-manage ${command} get <id>`,
+    details: { missing: ["id"] },
+  });
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+async function mergeOptionsFile(optionValues) {
+  const optionsFile = readStringOption(optionValues, "options-file");
+  if (!optionsFile) {
+    return optionValues;
+  }
+
+  const fileOptions = await readJsonInput(optionsFile, "`--options-file` input");
+  if (!isPlainObject(fileOptions)) {
+    throw new UsageError("`--options-file` must contain a JSON object.", {
+      code: "invalid_options_file",
+      hint: "Use a JSON object like `{ \"limit\": 5 }`.",
+    });
+  }
+
+  return {
+    ...fileOptions,
+    ...optionValues,
+  };
+}
+
+function assertSingleStdinConsumer(optionValues) {
+  const optionsFile = readStringOption(optionValues, "options-file");
+  const idsFile = readStringOption(optionValues, "ids-file");
+  const stdinIds = readBooleanOption(optionValues, "stdin") === true;
+  const stdinConsumers = [optionsFile === "-", idsFile === "-", stdinIds].filter(Boolean);
+
+  if (stdinConsumers.length > 1) {
+    throw new UsageError("Only one stdin-consuming flag can be used at a time.", {
+      code: "conflicting_stdin_inputs",
+      hint: "Use either `--options-file -`, `--ids-file -`, or `--stdin`.",
+    });
+  }
+}
+
+function applyAgentInputOptions(sub, optionValues, options) {
+  if (sub !== "get") {
+    return options;
+  }
+
+  const idsFile = readStringOption(optionValues, "ids-file");
+  const stdinIds = readBooleanOption(optionValues, "stdin") === true;
+  if (!idsFile && !stdinIds) {
+    return options;
+  }
+
+  if (hasOwn(optionValues, "stdin") && readBooleanOption(optionValues, "stdin") !== true) {
+    return options;
+  }
+
+  return {
+    ...options,
+    idsFile: stdinIds ? "-" : idsFile,
+  };
+}
+
+function buildAuthSetupOptions(optionValues, globalFlags = {}) {
+  const options = {
+    clientId: readStringOption(optionValues, "client-id"),
+    clientSecret: readStringOption(optionValues, "client-secret"),
+    confirmConfidentiality: readBooleanOption(optionValues, "confirm-confidentiality") === true,
+    openBrowser: readBooleanOption(optionValues, "open-browser"),
+    redirectUri: readStringOption(optionValues, "redirect-uri"),
+    region: readStringOption(optionValues, "region"),
+  };
+  if (globalFlags.noInput) {
+    options.noInput = true;
+  }
+  return options;
+}
+
+function buildAuthRevokeOptions(optionValues, globalFlags = {}) {
+  return {
+    dryRun: readBooleanOption(optionValues, "dry-run") === true,
+    yes:
+      globalFlags.yes === true ||
+      readBooleanOption(optionValues, "yes") === true ||
+      readBooleanOption(optionValues, "force") === true,
+  };
+}
+
+async function run(args) {
+  const helpRequested = hasFlag(args, "-h", "--help");
+  const versionRequested = hasFlag(args, "-v", "--version");
+  const globalFlags = readGlobalFlags(args);
+  const routingArgs = stripRoutingFlags(args);
+
+  if (routingArgs.length === 0) {
+    if (versionRequested && !helpRequested) {
+      console.log(`not-manage v${version}`);
+      return;
+    }
+
+    printGlobalHelp();
+    return;
+  }
+
+  const command = normalizeResourceCommand(routingArgs[0]);
+  const sub = routingArgs[1];
+
+  if (helpRequested) {
+    printCommandSpecificHelp(command, sub);
     return;
   }
 
-  const json = hasFlag(args, "--json");
-  const command = normalizeResourceCommand(args[0]);
-  const sub = args[1];
-  const { parsed: optionValues, positional } = parseOptions(args.slice(2));
+  const json = globalFlags.json;
+  const { parsed, positional } = parseOptions(routingArgs.slice(2));
+  assertSingleStdinConsumer(parsed);
+  const optionValues = await mergeOptionsFile(parsed);
   const redacted = resolveRedactionPreference(optionValues);
 
   if (maybePrintDefaultFields(command, sub, optionValues)) {
@@ -160,47 +863,115 @@ async function run(args) {
   }
 
   if (command === "setup") {
-    await setupWizard();
+    await setupWizard(buildAuthSetupOptions(optionValues, globalFlags));
     return;
   }
 
-  if (command === "auth" && sub === "setup") {
-    await authSetup();
-    return;
+  if (command === "auth") {
+    if (!sub) {
+      printAuthHelp();
+      return;
+    }
+
+    if (sub === "setup") {
+      await authSetup(buildAuthSetupOptions(optionValues, globalFlags));
+      return;
+    }
+
+    if (sub === "login") {
+      await authLogin({ json });
+      return;
+    }
+
+    if (sub === "status") {
+      await authStatus({ json, redacted });
+      return;
+    }
+
+    if (sub === "revoke") {
+      await authRevoke(buildAuthRevokeOptions(optionValues, globalFlags));
+      return;
+    }
+
+    throw new UsageError(
+      `Unknown subcommand for auth: ${sub}\nRun \`not-manage auth --help\`.`,
+      { code: "unknown_subcommand", hint: "not-manage auth --help" }
+    );
   }
 
-  if (command === "auth" && sub === "login") {
-    await authLogin();
+  if (command === "whoami") {
+    await whoAmI({ json, redacted });
     return;
   }
 
-  if (command === "auth" && sub === "status") {
-    await authStatus({ json });
+  if (command === "doctor") {
+    await doctor({
+      compact: globalFlags.compact,
+      failOn: readStringOption(optionValues, "fail-on"),
+      json,
+    });
     return;
   }
 
-  if (command === "auth" && sub === "revoke") {
-    await authRevoke();
+  if (command === "agent-context") {
+    await agentContext({
+      compact: globalFlags.compact,
+    });
     return;
   }
 
-  if (command === "whoami") {
-    await whoAmI({ json });
+  if (command === "request") {
+    await rawRequest({
+      method: routingArgs[1],
+      path: routingArgs[2],
+      query: readStringOption(optionValues, "query"),
+      bodyFile: readStringOption(optionValues, "body-file"),
+      dryRun: readBooleanOption(optionValues, "dry-run") === true,
+      write: readBooleanOption(optionValues, "write") === true,
+      compact: globalFlags.compact,
+      json,
+      redacted,
+    });
     return;
   }
 
   const resourceMetadata = getResourceMetadata(command);
+  if (resourceMetadata && !sub) {
+    printResourceOverview(command, resourceMetadata);
+    return;
+  }
+
   const handler = getResourceHandler(resourceMetadata, sub);
 
   if (resourceMetadata && handler) {
-    warnAboutRedaction(resourceMetadata, sub, optionValues, redacted);
-    await handler(
-      buildResourceOptions(resourceMetadata, sub, optionValues, positional, json, redacted)
+    const resourceOptions = buildResourceOptions(
+      resourceMetadata,
+      sub,
+      optionValues,
+      positional,
+      json,
+      redacted,
+      globalFlags.compact
     );
+    const resourceOptionsWithAgentInput = applyAgentInputOptions(sub, optionValues, resourceOptions);
+    assertRequiredResourceOptions(command, sub, resourceMetadata, resourceOptionsWithAgentInput);
+    assertResourceIdOption(command, sub, resourceOptionsWithAgentInput);
+    warnAboutRedaction(resourceMetadata, sub, optionValues, redacted);
+    await handler(resourceOptionsWithAgentInput);
     return;
   }
 
-  throw new Error(`Unknown command: ${args.join(" ")}`);
+  if (resourceMetadata) {
+    throw new UsageError(
+      `Unknown subcommand for ${command}: ${sub}\nRun \`not-manage ${command} --help\`.`,
+      { code: "unknown_subcommand", hint: `not-manage ${command} --help` }
+    );
+  }
+
+  throw new UsageError(
+    `Unknown command: ${routingArgs.join(" ")}\nRun \`not-manage --help\`.`,
+    { code: "unknown_command", hint: "not-manage --help" }
+  );
 }
 
 module.exports = {