cli-agent-mode 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gordey Levchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# cli-agent-mode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/cli-agent-mode)](https://www.npmjs.com/package/cli-agent-mode)
+[![CI](https://github.com/missingbits/cli-agent-mode/actions/workflows/ci.yml/badge.svg)](https://github.com/missingbits/cli-agent-mode/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/cli-agent-mode)](LICENSE)
+
+**Make any [commander.js](https://github.com/tj/commander.js) CLI usable by AI agents** (Claude Code, Cursor, Codex, Gemini CLI, Copilot) **without breaking it for humans.**
+
+Two lines turn your CLI into one that agents can drive reliably:
+
+- **`--json` output envelope** — every command prints exactly one JSON document on stdout: `{"ok":true,"data":...}` or `{"ok":false,"error":{...}}`.
+- **Machine-readable errors** — stable `code`, a human `message`, and a `suggestion` the agent can follow literally. Commander usage errors are mapped too (`UNKNOWN_OPTION`, `MISSING_ARGUMENT`, ...).
+- **Self-description** — `mycli describe [command]` (and `--help --json`) print the full CLI schema in one call: arguments, option flags, defaults, choices, subcommands. Compact by design (falsy fields and empty lists are omitted) to save agent tokens.
+- **Auto-detects agents** — JSON turns on automatically under `AI_AGENT`, `CLAUDECODE`, `CURSOR_AGENT`, `GEMINI_CLI`, `CODEX_SANDBOX`, ... (precedence: `--json` > `CLI_AGENT_MODE` > auto-detect)
+- **Escape hatch** — `CLI_AGENT_MODE=human` forces human output even under an agent, `CLI_AGENT_MODE=json` forces JSON.
+- **Stable exit codes** — `0` ok, `1` runtime error, `2` usage error.
+- **Clean stdout** — stray `console.log` inside actions is redirected to stderr in JSON mode.
+
+Zero dependencies. ~4 kB gzipped. ESM and CommonJS, Node 20+, commander 12+.
+
+```bash
+npm i cli-agent-mode
+```
+
+## Usage
+
+```ts
+import { Command } from 'commander';
+import { AgentError, agentMode, run } from 'cli-agent-mode';
+
+const program = agentMode(new Command('deployctl')).version('1.0.0'); // 1. wrap the program
+
+program
+  .command('deploy')
+  .argument('<env>', 'environment name')
+  .option('--dry-run', 'show the plan without deploying')
+  .action(async (env, opts) => {
+    if (!['staging', 'prod'].includes(env)) {
+      throw new AgentError('ENV_NOT_FOUND', `Unknown environment "${env}"`, {
+        suggestion: 'Use one of: staging, prod.',
+      });
+    }
+    return { env, url: `https://${env}.example.com` }; // return data instead of printing it
+  });
+
+await run(program); // 2. replace program.parseAsync()
+```
+
+What an agent sees:
+
+```console
+$ deployctl deploy prod --json
+{"ok":true,"data":{"env":"prod","url":"https://prod.example.com"}}
+
+$ deployctl deploy mars --json          # exit code 1
+{"ok":false,"error":{"code":"ENV_NOT_FOUND","message":"Unknown environment \"mars\"","suggestion":"Use one of: staging, prod."}}
+
+$ deployctl deploy --json               # exit code 2
+{"ok":false,"error":{"code":"MISSING_ARGUMENT","message":"missing required argument 'env'","suggestion":"Run \"deployctl describe deploy\" to see accepted arguments and options."}}
+
+$ deployctl describe deploy --json
+{"ok":true,"data":{"name":"deploy","description":"Deploy an environment","usage":"deployctl deploy [options] <env>","arguments":[{"name":"env","description":"environment name","required":true}],"options":[{"flags":"--dry-run","description":"show the plan without deploying"}]}}
+```
+
+What a human sees (same CLI, no agent detected):
+
+```console
+$ deployctl deploy mars
+error: Unknown environment "mars"
+hint: Use one of: staging, prod.
+```
+
+## API
+
+### `agentMode(program, options?)`
+
+Call right after `new Command()`, **before** defining subcommands. Adds the `--json` flag and the `describe` command, and lets `.action()` handlers return a result.
+
+| option | default | |
+|---|---|---|
+| `autoDetect` | `true` | enable JSON when an AI agent is detected |
+| `describeCommand` | `'describe'` | name of the schema command, `false` to disable |
+| `formatHuman` | strings as-is, other values as pretty JSON | `(data, command) => string \| undefined` |
+
+### `run(program, options?)` → `Promise<{ mode, exitCode, envelope }>`
+
+Parses `process.argv`, runs the action, prints the result/error, sets `process.exitCode`. For tests pass `args`, `env`, `stdout`, `stderr`, `json`, `setExitCode: false`.
+
+### `new AgentError(code, message, { suggestion?, details?, exitCode? })`
+
+Throw it from an action for a structured error. Anything else thrown becomes `INTERNAL_ERROR`.
+
+### `describeCommand(cmd)`, `detectAgent(env?)`
+
+Lower-level helpers: the schema generator and the agent detector.
+
+### Error codes from commander
+
+`UNKNOWN_OPTION`, `UNKNOWN_COMMAND`, `MISSING_ARGUMENT`, `MISSING_OPTION_VALUE`, `MISSING_REQUIRED_OPTION`, `INVALID_ARGUMENT`, `EXCESS_ARGUMENTS`, `CONFLICTING_OPTIONS`, `MISSING_COMMAND`, `USAGE_ERROR`.
+
+## Benchmark: does it actually help an agent?
+
+Same tiny notes CLI, written twice: plain commander vs. with `cli-agent-mode`. Claude Code (headless, Claude Haiku) gets the same task: add notes, mark one done, delete a tag (the CLI refuses to delete unfinished notes without `--force`), hit a missing id, report the result. 6 runs per variant:
+
+| | plain commander | cli-agent-mode |
+|---|:-:|:-:|
+| task completed | 6/6 | 6/6 |
+| CLI calls (avg, range) | 17.3 (16–19) | **11.3 (9–12)** |
+| `--help` calls per run | 4 | **1** |
+| failed calls (avg) | 3.0 | **1.8** |
+| CLI output (avg bytes) | ~1100 | ~2000 |
+
+**−35% CLI calls with the same success rate.** The agent learns the whole CLI from one `--help` (which returns the schema of every command) instead of reading help page by page, and recovers from errors using `code` + `suggestion`. The trade-off is ~1.8× more output (≈250 tokens per task here).
+
+Reproduce: [`examples/playground/agent-bench.sh`](examples/playground/agent-bench.sh) `5 haiku` (requires Claude Code).
+
+## Why not ...
+
+| | `--json` from return values | structured errors + suggestion | schema command | agent auto-detect |
+|---|:-:|:-:|:-:|:-:|
+| plain commander | ✗ | ✗ | ✗ | ✗ |
+| oclif (`enableJsonFlag`) | ✓ | partial | ✗ | ✗ |
+| hand-rolled `if (opts.json)` | per command | usually ✗ | ✗ | ✗ |
+| **cli-agent-mode** | ✓ | ✓ | ✓ | ✓ |
+
+If you are already on oclif, you have `--json`. If you are on commander — the most used Node CLI framework — this is the missing piece.
+
+## Limitations
+
+- Subcommands must be created with `program.command()` (or added via `addCommand()` *before* their `.action()` is set) so return values can be captured.
+- `--json` is reserved: it is removed from argv before parsing (except after `--`).
+- In JSON mode `console.log/info/debug` are redirected to stderr, but direct `process.stdout.write` calls inside actions are not — return data instead.
+- Typed `@commander-js/extra-typings` is not supported yet.
+
+## License
+
+MIT

package/dist/commander-augment.d.ts

@@ -0,0 +1,8 @@
+import 'commander';
+
+declare module 'commander' {
+  interface Command {
+    /** With cli-agent-mode the handler may return a JSON-serializable result. */
+    action(fn: (this: this, ...args: any[]) => unknown): this;
+  }
+}

package/dist/index.cjs

@@ -0,0 +1,337 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let commander = require("commander");
+let node_util = require("node:util");
+//#region src/detect.ts
+/**
+* Synchronous, dependency-free detection of AI coding agents.
+* Env variables mirror @vercel/detect-agent (Nov 2026) plus the `AI_AGENT` convention.
+* CURSOR_TRACE_ID is deliberately ignored: it is also set in Cursor's terminal for humans.
+* Returns the agent name or `undefined`.
+*/
+function detectAgent(env = process.env) {
+	const aiAgent = env.AI_AGENT?.trim();
+	if (aiAgent) return aiAgent;
+	if (env.CLAUDECODE || env.CLAUDE_CODE) return "claude";
+	if (env.CURSOR_AGENT || env.CURSOR_EXTENSION_HOST_ROLE === "agent-exec") return "cursor-cli";
+	if (env.GEMINI_CLI) return "gemini";
+	if (env.CODEX_SANDBOX || env.CODEX_CI || env.CODEX_THREAD_ID) return "codex";
+	if (env.ANTIGRAVITY_AGENT) return "antigravity";
+	if (env.AUGMENT_AGENT) return "augment-cli";
+	if (env.OPENCODE === "1" || env.OPENCODE_CLIENT) return "opencode";
+	if (env.COPILOT_MODEL || env.COPILOT_ALLOW_ALL) return "github-copilot";
+	if (env.REPL_ID) return "replit";
+}
+//#endregion
+//#region src/describe.ts
+const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0 && v !== "" && v !== false && !(Array.isArray(v) && v.length === 0)));
+function describeArgument(a) {
+	return clean({
+		name: a.name(),
+		description: a.description,
+		required: a.required || void 0,
+		variadic: a.variadic || void 0,
+		default: a.defaultValue,
+		choices: a.argChoices
+	});
+}
+function describeOption(o) {
+	return clean({
+		flags: o.flags,
+		description: o.description,
+		required: o.mandatory || void 0,
+		default: o.defaultValue,
+		choices: o.argChoices,
+		env: o.envVar
+	});
+}
+function commandPath(cmd) {
+	const parts = [];
+	for (let c = cmd; c; c = c.parent) parts.unshift(c.name());
+	return parts.join(" ");
+}
+const isHidden = (c) => c._hidden === true;
+/** Compact JSON schema of a command and all of its visible subcommands. */
+function describeCommand(cmd) {
+	return clean({
+		name: cmd.name(),
+		description: cmd.description(),
+		usage: `${commandPath(cmd)} ${cmd.usage()}`.trim(),
+		aliases: cmd.aliases(),
+		arguments: cmd.registeredArguments.map(describeArgument),
+		options: cmd.options.filter((o) => !o.hidden).map(describeOption),
+		commands: cmd.commands.filter((c) => !isHidden(c)).map(describeCommand)
+	});
+}
+/** Resolve `["deploy", "preview"]` to the nested subcommand (by name or alias). */
+function findCommand(root, path) {
+	let cur = root;
+	for (const part of path) {
+		cur = cur?.commands.find((c) => c.name() === part || c.aliases().includes(part));
+		if (!cur) return void 0;
+	}
+	return cur;
+}
+//#endregion
+//#region src/errors.ts
+/**
+* An error with a stable machine-readable `code`.
+*
+* @example
+* throw new AgentError('ENV_NOT_FOUND', `Environment "${env}" does not exist`, {
+*   suggestion: 'Run "mycli env list" to see available environments.',
+* });
+*/
+var AgentError = class extends Error {
+	code;
+	suggestion;
+	details;
+	exitCode;
+	constructor(code, message, options = {}) {
+		super(message);
+		this.name = "AgentError";
+		this.code = code;
+		this.suggestion = options.suggestion;
+		this.details = options.details;
+		this.exitCode = options.exitCode ?? 1;
+	}
+};
+/** Exit codes used by cli-agent-mode. */
+const EXIT = {
+	OK: 0,
+	ERROR: 1,
+	USAGE: 2
+};
+//#endregion
+//#region src/agent-mode.ts
+const states = /* @__PURE__ */ new WeakMap();
+const rootOf = (cmd) => {
+	let c = cmd;
+	while (c.parent) c = c.parent;
+	return c;
+};
+/** Make every `.action()` handler's return value available as the command result. */
+function patch(cmd) {
+	const proto = Object.getPrototypeOf(cmd);
+	cmd.action = function(fn) {
+		return proto.action.call(this, async function(...args) {
+			const value = await fn.apply(this, args);
+			const state = states.get(rootOf(this));
+			if (state) state.result = {
+				value,
+				command: this
+			};
+		});
+	};
+	cmd.createCommand = (name) => patch(proto.createCommand.call(cmd, name));
+	const addCommand = cmd.addCommand;
+	cmd.addCommand = function(sub, opts) {
+		walk(sub, patch);
+		return addCommand.call(this, sub, opts);
+	};
+	return cmd;
+}
+function walk(cmd, fn) {
+	fn(cmd);
+	for (const sub of cmd.commands) walk(sub, fn);
+}
+/**
+* Turn a commander program into an agent-friendly CLI.
+* Call it right after creating the program, before defining subcommands.
+*
+* @example
+* const program = agentMode(new Command('mycli'));
+* program.command('deploy <env>').action(async (env) => ({ url: `https://${env}.example.com` }));
+* await run(program);
+*/
+function agentMode(program, options = {}) {
+	const state = { options: {
+		autoDetect: options.autoDetect ?? true,
+		describeCommand: options.describeCommand ?? "describe",
+		formatHuman: options.formatHuman
+	} };
+	states.set(program, state);
+	walk(program, patch);
+	program.option("--json", "print one JSON envelope on stdout (auto-on for AI agents)");
+	const name = state.options.describeCommand;
+	if (name) program.command(`${name} [command...]`).description("print the CLI schema as JSON").action((path = []) => {
+		const target = findCommand(program, path);
+		if (!target) throw new AgentError("UNKNOWN_COMMAND", `Unknown command: ${path.join(" ")}`, {
+			suggestion: `Run "${program.name()} ${name}" to list all commands.`,
+			exitCode: EXIT.USAGE
+		});
+		return describeCommand(target);
+	});
+	return program;
+}
+const USAGE_CODES = {
+	"commander.unknownOption": "UNKNOWN_OPTION",
+	"commander.unknownCommand": "UNKNOWN_COMMAND",
+	"commander.missingArgument": "MISSING_ARGUMENT",
+	"commander.optionMissingArgument": "MISSING_OPTION_VALUE",
+	"commander.missingMandatoryOptionValue": "MISSING_REQUIRED_OPTION",
+	"commander.invalidArgument": "INVALID_ARGUMENT",
+	"commander.excessArguments": "EXCESS_ARGUMENTS",
+	"commander.conflictingOption": "CONFLICTING_OPTIONS",
+	"commander.help": "MISSING_COMMAND"
+};
+function extractJsonFlag(args) {
+	const end = args.indexOf("--");
+	const head = end === -1 ? args : args.slice(0, end);
+	const tail = end === -1 ? [] : args.slice(end);
+	const json = head.includes("--json");
+	return {
+		args: [...head.filter((a) => a !== "--json"), ...tail],
+		json
+	};
+}
+const defaultHuman = (data) => data === void 0 || data === null ? void 0 : typeof data === "string" ? data : JSON.stringify(data, null, 2);
+/** Parse arguments, run the matching action and print the result or error in the right format. */
+async function run(program, runOptions = {}) {
+	const state = states.get(program);
+	if (!state) throw new Error("cli-agent-mode: call agentMode(program) before run(program)");
+	state.result = void 0;
+	const env = runOptions.env ?? process.env;
+	const stdout = runOptions.stdout ?? process.stdout;
+	const stderr = runOptions.stderr ?? process.stderr;
+	const extracted = extractJsonFlag(runOptions.args ?? process.argv.slice(2));
+	const forced = env.CLI_AGENT_MODE === "json" ? true : env.CLI_AGENT_MODE === "human" ? false : void 0;
+	const json = runOptions.json ?? (extracted.json || (forced ?? (state.options.autoDetect && detectAgent(env) !== void 0)));
+	const mode = json ? "json" : "human";
+	let outBuf = "";
+	let errorCommand = program;
+	const restore = [];
+	walk(program, (cmd) => {
+		const prevOutput = cmd.configureOutput();
+		const prevHelp = cmd.configureHelp();
+		restore.push(() => {
+			cmd.configureOutput(prevOutput);
+			cmd.configureHelp(prevHelp);
+		});
+		cmd.exitOverride();
+		cmd.configureOutput({
+			...prevOutput,
+			writeOut: (s) => json ? outBuf += s : stdout.write(s),
+			writeErr: (s) => json ? void 0 : stderr.write(s),
+			outputError: (s, write) => {
+				errorCommand = cmd;
+				if (!json) write(s);
+			}
+		});
+		if (json) cmd.configureHelp({
+			...prevHelp,
+			formatHelp: (c) => JSON.stringify({
+				ok: true,
+				data: describeCommand(c)
+			}) + "\n"
+		});
+	});
+	const consoleKeys = [
+		"log",
+		"info",
+		"debug"
+	];
+	const savedConsole = consoleKeys.map((k) => console[k]);
+	if (json) for (const k of consoleKeys) console[k] = (...a) => void stderr.write((0, node_util.format)(...a) + "\n");
+	let envelope;
+	let exitCode = EXIT.OK;
+	let printed = false;
+	try {
+		await program.parseAsync(extracted.args, { from: "user" });
+		const result = state.result;
+		const value = result?.value;
+		envelope = {
+			ok: true,
+			data: value ?? null
+		};
+		if (!json) {
+			const text = (state.options.formatHuman ?? defaultHuman)(value, result?.command ?? program);
+			if (text !== void 0) stdout.write(text + "\n");
+			printed = true;
+		}
+	} catch (err) {
+		if (err instanceof commander.CommanderError && (err.code === "commander.helpDisplayed" || err.code === "commander.help" && err.exitCode === 0)) {
+			if (json) stdout.write(outBuf);
+			return finish({
+				ok: true,
+				data: null
+			}, EXIT.OK, true);
+		}
+		if (err instanceof commander.CommanderError && err.code === "commander.version") {
+			envelope = {
+				ok: true,
+				data: { version: outBuf.trim() || program.version() }
+			};
+			exitCode = EXIT.OK;
+			if (!json) printed = true;
+		} else {
+			const { payload, code } = toPayload(err, program, errorCommand, state.options.describeCommand);
+			envelope = {
+				ok: false,
+				error: payload
+			};
+			exitCode = code;
+			if (!json) {
+				if (!(err instanceof commander.CommanderError)) stderr.write(`error: ${payload.message}\n`);
+				if (payload.suggestion) stderr.write(`hint: ${payload.suggestion}\n`);
+				printed = true;
+			}
+		}
+	} finally {
+		consoleKeys.forEach((k, i) => console[k] = savedConsole[i]);
+		restore.forEach((r) => r());
+	}
+	return finish(envelope, exitCode, printed);
+	function finish(env, code, done) {
+		if (json && !done) stdout.write(JSON.stringify(env) + "\n");
+		if (runOptions.setExitCode ?? true) process.exitCode = code;
+		return {
+			mode,
+			exitCode: code,
+			envelope: env
+		};
+	}
+}
+function toPayload(err, root, at, describeName) {
+	if (err instanceof AgentError) return {
+		payload: strip({
+			code: err.code,
+			message: err.message,
+			suggestion: err.suggestion,
+			details: err.details
+		}),
+		code: err.exitCode
+	};
+	if (err instanceof commander.CommanderError) {
+		const sub = commandPath(at).split(" ").slice(1).join(" ");
+		const suggestion = describeName ? `Run "${[
+			root.name(),
+			describeName,
+			sub
+		].filter(Boolean).join(" ")}" to see accepted arguments and options.` : `Run "${commandPath(at)} --help" to see usage.`;
+		const message = err.code === "commander.help" ? "A subcommand is required." : err.message.replace(/^error:\s*/, "");
+		return {
+			payload: {
+				code: USAGE_CODES[err.code] ?? "USAGE_ERROR",
+				message,
+				suggestion
+			},
+			code: EXIT.USAGE
+		};
+	}
+	return {
+		payload: {
+			code: "INTERNAL_ERROR",
+			message: err instanceof Error ? err.message : String(err)
+		},
+		code: EXIT.ERROR
+	};
+}
+const strip = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
+//#endregion
+exports.AgentError = AgentError;
+exports.EXIT = EXIT;
+exports.agentMode = agentMode;
+exports.describeCommand = describeCommand;
+exports.detectAgent = detectAgent;
+exports.findCommand = findCommand;
+exports.run = run;

package/dist/index.d.cts

@@ -0,0 +1,135 @@
+/// <reference path="./commander-augment.d.ts" />
+import { Command } from "commander";
+
+//#region src/errors.d.ts
+interface AgentErrorOptions {
+  /** One concrete next step the agent (or human) can follow literally. */
+  suggestion?: string;
+  /** Any JSON-serializable context: ids, paths, limits, etc. */
+  details?: unknown;
+  /** Process exit code. Defaults to 1. */
+  exitCode?: number;
+}
+/**
+ * An error with a stable machine-readable `code`.
+ *
+ * @example
+ * throw new AgentError('ENV_NOT_FOUND', `Environment "${env}" does not exist`, {
+ *   suggestion: 'Run "mycli env list" to see available environments.',
+ * });
+ */
+declare class AgentError extends Error {
+  readonly code: string;
+  readonly suggestion?: string;
+  readonly details?: unknown;
+  readonly exitCode: number;
+  constructor(code: string, message: string, options?: AgentErrorOptions);
+}
+interface ErrorPayload {
+  code: string;
+  message: string;
+  suggestion?: string;
+  details?: unknown;
+}
+type Envelope<T = unknown> = {
+  ok: true;
+  data: T;
+} | {
+  ok: false;
+  error: ErrorPayload;
+};
+/** Exit codes used by cli-agent-mode. */
+declare const EXIT: {
+  readonly OK: 0;
+  readonly ERROR: 1;
+  readonly USAGE: 2;
+};
+//#endregion
+//#region src/agent-mode.d.ts
+interface AgentModeOptions {
+  /** Switch to JSON automatically when an AI agent is detected (AI_AGENT, CLAUDECODE, CURSOR_AGENT, ...). Default: true. */
+  autoDetect?: boolean;
+  /** Name of the self-description command, or `false` to skip adding it. Default: "describe". */
+  describeCommand?: string | false;
+  /** Render action results for humans. Default: strings as-is, everything else as pretty JSON. */
+  formatHuman?: (data: unknown, command: Command) => string | undefined;
+}
+interface RunOptions {
+  /** User arguments (without node and script path). Default: process.argv.slice(2). */
+  args?: string[];
+  /** Force JSON (`true`) or human (`false`) output, bypassing flag and agent detection. */
+  json?: boolean;
+  env?: NodeJS.ProcessEnv;
+  stdout?: {
+    write(chunk: string): unknown;
+  };
+  stderr?: {
+    write(chunk: string): unknown;
+  };
+  /** Set `process.exitCode`. Default: true. */
+  setExitCode?: boolean;
+}
+interface RunResult {
+  mode: 'json' | 'human';
+  exitCode: number;
+  envelope: Envelope;
+}
+/**
+ * Turn a commander program into an agent-friendly CLI.
+ * Call it right after creating the program, before defining subcommands.
+ *
+ * @example
+ * const program = agentMode(new Command('mycli'));
+ * program.command('deploy <env>').action(async (env) => ({ url: `https://${env}.example.com` }));
+ * await run(program);
+ */
+declare function agentMode<T extends Command>(program: T, options?: AgentModeOptions): T;
+/** Parse arguments, run the matching action and print the result or error in the right format. */
+declare function run(program: Command, runOptions?: RunOptions): Promise<RunResult>;
+//#endregion
+//#region src/describe.d.ts
+interface ArgumentSchema {
+  name: string;
+  description?: string;
+  /** present only when true */
+  required?: true;
+  /** present only when true */
+  variadic?: true;
+  default?: unknown;
+  choices?: readonly string[];
+}
+interface OptionSchema {
+  /** commander flags, e.g. "-t, --tag <tag>" */
+  flags: string;
+  description?: string;
+  /** present only when the option itself must be passed */
+  required?: true;
+  default?: unknown;
+  choices?: readonly string[];
+  env?: string;
+}
+interface CommandSchema {
+  name: string;
+  description?: string;
+  /** full invocation, e.g. "mycli deploy [options] <env>" */
+  usage: string;
+  aliases?: string[];
+  arguments?: ArgumentSchema[];
+  options?: OptionSchema[];
+  commands?: CommandSchema[];
+}
+/** Compact JSON schema of a command and all of its visible subcommands. */
+declare function describeCommand(cmd: Command): CommandSchema;
+/** Resolve `["deploy", "preview"]` to the nested subcommand (by name or alias). */
+declare function findCommand(root: Command, path: string[]): Command | undefined;
+//#endregion
+//#region src/detect.d.ts
+/**
+ * Synchronous, dependency-free detection of AI coding agents.
+ * Env variables mirror @vercel/detect-agent (Nov 2026) plus the `AI_AGENT` convention.
+ * CURSOR_TRACE_ID is deliberately ignored: it is also set in Cursor's terminal for humans.
+ * Returns the agent name or `undefined`.
+ */
+declare function detectAgent(env?: NodeJS.ProcessEnv): string | undefined;
+//#endregion
+export { AgentError, type AgentErrorOptions, type AgentModeOptions, type ArgumentSchema, type CommandSchema, EXIT, type Envelope, type ErrorPayload, type OptionSchema, type RunOptions, type RunResult, agentMode, describeCommand, detectAgent, findCommand, run };

package/dist/index.d.mts

@@ -0,0 +1,135 @@
+/// <reference path="./commander-augment.d.ts" />
+import { Command } from "commander";
+
+//#region src/errors.d.ts
+interface AgentErrorOptions {
+  /** One concrete next step the agent (or human) can follow literally. */
+  suggestion?: string;
+  /** Any JSON-serializable context: ids, paths, limits, etc. */
+  details?: unknown;
+  /** Process exit code. Defaults to 1. */
+  exitCode?: number;
+}
+/**
+ * An error with a stable machine-readable `code`.
+ *
+ * @example
+ * throw new AgentError('ENV_NOT_FOUND', `Environment "${env}" does not exist`, {
+ *   suggestion: 'Run "mycli env list" to see available environments.',
+ * });
+ */
+declare class AgentError extends Error {
+  readonly code: string;
+  readonly suggestion?: string;
+  readonly details?: unknown;
+  readonly exitCode: number;
+  constructor(code: string, message: string, options?: AgentErrorOptions);
+}
+interface ErrorPayload {
+  code: string;
+  message: string;
+  suggestion?: string;
+  details?: unknown;
+}
+type Envelope<T = unknown> = {
+  ok: true;
+  data: T;
+} | {
+  ok: false;
+  error: ErrorPayload;
+};
+/** Exit codes used by cli-agent-mode. */
+declare const EXIT: {
+  readonly OK: 0;
+  readonly ERROR: 1;
+  readonly USAGE: 2;
+};
+//#endregion
+//#region src/agent-mode.d.ts
+interface AgentModeOptions {
+  /** Switch to JSON automatically when an AI agent is detected (AI_AGENT, CLAUDECODE, CURSOR_AGENT, ...). Default: true. */
+  autoDetect?: boolean;
+  /** Name of the self-description command, or `false` to skip adding it. Default: "describe". */
+  describeCommand?: string | false;
+  /** Render action results for humans. Default: strings as-is, everything else as pretty JSON. */
+  formatHuman?: (data: unknown, command: Command) => string | undefined;
+}
+interface RunOptions {
+  /** User arguments (without node and script path). Default: process.argv.slice(2). */
+  args?: string[];
+  /** Force JSON (`true`) or human (`false`) output, bypassing flag and agent detection. */
+  json?: boolean;
+  env?: NodeJS.ProcessEnv;
+  stdout?: {
+    write(chunk: string): unknown;
+  };
+  stderr?: {
+    write(chunk: string): unknown;
+  };
+  /** Set `process.exitCode`. Default: true. */
+  setExitCode?: boolean;
+}
+interface RunResult {
+  mode: 'json' | 'human';
+  exitCode: number;
+  envelope: Envelope;
+}
+/**
+ * Turn a commander program into an agent-friendly CLI.
+ * Call it right after creating the program, before defining subcommands.
+ *
+ * @example
+ * const program = agentMode(new Command('mycli'));
+ * program.command('deploy <env>').action(async (env) => ({ url: `https://${env}.example.com` }));
+ * await run(program);
+ */
+declare function agentMode<T extends Command>(program: T, options?: AgentModeOptions): T;
+/** Parse arguments, run the matching action and print the result or error in the right format. */
+declare function run(program: Command, runOptions?: RunOptions): Promise<RunResult>;
+//#endregion
+//#region src/describe.d.ts
+interface ArgumentSchema {
+  name: string;
+  description?: string;
+  /** present only when true */
+  required?: true;
+  /** present only when true */
+  variadic?: true;
+  default?: unknown;
+  choices?: readonly string[];
+}
+interface OptionSchema {
+  /** commander flags, e.g. "-t, --tag <tag>" */
+  flags: string;
+  description?: string;
+  /** present only when the option itself must be passed */
+  required?: true;
+  default?: unknown;
+  choices?: readonly string[];
+  env?: string;
+}
+interface CommandSchema {
+  name: string;
+  description?: string;
+  /** full invocation, e.g. "mycli deploy [options] <env>" */
+  usage: string;
+  aliases?: string[];
+  arguments?: ArgumentSchema[];
+  options?: OptionSchema[];
+  commands?: CommandSchema[];
+}
+/** Compact JSON schema of a command and all of its visible subcommands. */
+declare function describeCommand(cmd: Command): CommandSchema;
+/** Resolve `["deploy", "preview"]` to the nested subcommand (by name or alias). */
+declare function findCommand(root: Command, path: string[]): Command | undefined;
+//#endregion
+//#region src/detect.d.ts
+/**
+ * Synchronous, dependency-free detection of AI coding agents.
+ * Env variables mirror @vercel/detect-agent (Nov 2026) plus the `AI_AGENT` convention.
+ * CURSOR_TRACE_ID is deliberately ignored: it is also set in Cursor's terminal for humans.
+ * Returns the agent name or `undefined`.
+ */
+declare function detectAgent(env?: NodeJS.ProcessEnv): string | undefined;
+//#endregion
+export { AgentError, type AgentErrorOptions, type AgentModeOptions, type ArgumentSchema, type CommandSchema, EXIT, type Envelope, type ErrorPayload, type OptionSchema, type RunOptions, type RunResult, agentMode, describeCommand, detectAgent, findCommand, run };

package/dist/index.mjs

@@ -0,0 +1,330 @@
+import { CommanderError } from "commander";
+import { format } from "node:util";
+//#region src/detect.ts
+/**
+* Synchronous, dependency-free detection of AI coding agents.
+* Env variables mirror @vercel/detect-agent (Nov 2026) plus the `AI_AGENT` convention.
+* CURSOR_TRACE_ID is deliberately ignored: it is also set in Cursor's terminal for humans.
+* Returns the agent name or `undefined`.
+*/
+function detectAgent(env = process.env) {
+	const aiAgent = env.AI_AGENT?.trim();
+	if (aiAgent) return aiAgent;
+	if (env.CLAUDECODE || env.CLAUDE_CODE) return "claude";
+	if (env.CURSOR_AGENT || env.CURSOR_EXTENSION_HOST_ROLE === "agent-exec") return "cursor-cli";
+	if (env.GEMINI_CLI) return "gemini";
+	if (env.CODEX_SANDBOX || env.CODEX_CI || env.CODEX_THREAD_ID) return "codex";
+	if (env.ANTIGRAVITY_AGENT) return "antigravity";
+	if (env.AUGMENT_AGENT) return "augment-cli";
+	if (env.OPENCODE === "1" || env.OPENCODE_CLIENT) return "opencode";
+	if (env.COPILOT_MODEL || env.COPILOT_ALLOW_ALL) return "github-copilot";
+	if (env.REPL_ID) return "replit";
+}
+//#endregion
+//#region src/describe.ts
+const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0 && v !== "" && v !== false && !(Array.isArray(v) && v.length === 0)));
+function describeArgument(a) {
+	return clean({
+		name: a.name(),
+		description: a.description,
+		required: a.required || void 0,
+		variadic: a.variadic || void 0,
+		default: a.defaultValue,
+		choices: a.argChoices
+	});
+}
+function describeOption(o) {
+	return clean({
+		flags: o.flags,
+		description: o.description,
+		required: o.mandatory || void 0,
+		default: o.defaultValue,
+		choices: o.argChoices,
+		env: o.envVar
+	});
+}
+function commandPath(cmd) {
+	const parts = [];
+	for (let c = cmd; c; c = c.parent) parts.unshift(c.name());
+	return parts.join(" ");
+}
+const isHidden = (c) => c._hidden === true;
+/** Compact JSON schema of a command and all of its visible subcommands. */
+function describeCommand(cmd) {
+	return clean({
+		name: cmd.name(),
+		description: cmd.description(),
+		usage: `${commandPath(cmd)} ${cmd.usage()}`.trim(),
+		aliases: cmd.aliases(),
+		arguments: cmd.registeredArguments.map(describeArgument),
+		options: cmd.options.filter((o) => !o.hidden).map(describeOption),
+		commands: cmd.commands.filter((c) => !isHidden(c)).map(describeCommand)
+	});
+}
+/** Resolve `["deploy", "preview"]` to the nested subcommand (by name or alias). */
+function findCommand(root, path) {
+	let cur = root;
+	for (const part of path) {
+		cur = cur?.commands.find((c) => c.name() === part || c.aliases().includes(part));
+		if (!cur) return void 0;
+	}
+	return cur;
+}
+//#endregion
+//#region src/errors.ts
+/**
+* An error with a stable machine-readable `code`.
+*
+* @example
+* throw new AgentError('ENV_NOT_FOUND', `Environment "${env}" does not exist`, {
+*   suggestion: 'Run "mycli env list" to see available environments.',
+* });
+*/
+var AgentError = class extends Error {
+	code;
+	suggestion;
+	details;
+	exitCode;
+	constructor(code, message, options = {}) {
+		super(message);
+		this.name = "AgentError";
+		this.code = code;
+		this.suggestion = options.suggestion;
+		this.details = options.details;
+		this.exitCode = options.exitCode ?? 1;
+	}
+};
+/** Exit codes used by cli-agent-mode. */
+const EXIT = {
+	OK: 0,
+	ERROR: 1,
+	USAGE: 2
+};
+//#endregion
+//#region src/agent-mode.ts
+const states = /* @__PURE__ */ new WeakMap();
+const rootOf = (cmd) => {
+	let c = cmd;
+	while (c.parent) c = c.parent;
+	return c;
+};
+/** Make every `.action()` handler's return value available as the command result. */
+function patch(cmd) {
+	const proto = Object.getPrototypeOf(cmd);
+	cmd.action = function(fn) {
+		return proto.action.call(this, async function(...args) {
+			const value = await fn.apply(this, args);
+			const state = states.get(rootOf(this));
+			if (state) state.result = {
+				value,
+				command: this
+			};
+		});
+	};
+	cmd.createCommand = (name) => patch(proto.createCommand.call(cmd, name));
+	const addCommand = cmd.addCommand;
+	cmd.addCommand = function(sub, opts) {
+		walk(sub, patch);
+		return addCommand.call(this, sub, opts);
+	};
+	return cmd;
+}
+function walk(cmd, fn) {
+	fn(cmd);
+	for (const sub of cmd.commands) walk(sub, fn);
+}
+/**
+* Turn a commander program into an agent-friendly CLI.
+* Call it right after creating the program, before defining subcommands.
+*
+* @example
+* const program = agentMode(new Command('mycli'));
+* program.command('deploy <env>').action(async (env) => ({ url: `https://${env}.example.com` }));
+* await run(program);
+*/
+function agentMode(program, options = {}) {
+	const state = { options: {
+		autoDetect: options.autoDetect ?? true,
+		describeCommand: options.describeCommand ?? "describe",
+		formatHuman: options.formatHuman
+	} };
+	states.set(program, state);
+	walk(program, patch);
+	program.option("--json", "print one JSON envelope on stdout (auto-on for AI agents)");
+	const name = state.options.describeCommand;
+	if (name) program.command(`${name} [command...]`).description("print the CLI schema as JSON").action((path = []) => {
+		const target = findCommand(program, path);
+		if (!target) throw new AgentError("UNKNOWN_COMMAND", `Unknown command: ${path.join(" ")}`, {
+			suggestion: `Run "${program.name()} ${name}" to list all commands.`,
+			exitCode: EXIT.USAGE
+		});
+		return describeCommand(target);
+	});
+	return program;
+}
+const USAGE_CODES = {
+	"commander.unknownOption": "UNKNOWN_OPTION",
+	"commander.unknownCommand": "UNKNOWN_COMMAND",
+	"commander.missingArgument": "MISSING_ARGUMENT",
+	"commander.optionMissingArgument": "MISSING_OPTION_VALUE",
+	"commander.missingMandatoryOptionValue": "MISSING_REQUIRED_OPTION",
+	"commander.invalidArgument": "INVALID_ARGUMENT",
+	"commander.excessArguments": "EXCESS_ARGUMENTS",
+	"commander.conflictingOption": "CONFLICTING_OPTIONS",
+	"commander.help": "MISSING_COMMAND"
+};
+function extractJsonFlag(args) {
+	const end = args.indexOf("--");
+	const head = end === -1 ? args : args.slice(0, end);
+	const tail = end === -1 ? [] : args.slice(end);
+	const json = head.includes("--json");
+	return {
+		args: [...head.filter((a) => a !== "--json"), ...tail],
+		json
+	};
+}
+const defaultHuman = (data) => data === void 0 || data === null ? void 0 : typeof data === "string" ? data : JSON.stringify(data, null, 2);
+/** Parse arguments, run the matching action and print the result or error in the right format. */
+async function run(program, runOptions = {}) {
+	const state = states.get(program);
+	if (!state) throw new Error("cli-agent-mode: call agentMode(program) before run(program)");
+	state.result = void 0;
+	const env = runOptions.env ?? process.env;
+	const stdout = runOptions.stdout ?? process.stdout;
+	const stderr = runOptions.stderr ?? process.stderr;
+	const extracted = extractJsonFlag(runOptions.args ?? process.argv.slice(2));
+	const forced = env.CLI_AGENT_MODE === "json" ? true : env.CLI_AGENT_MODE === "human" ? false : void 0;
+	const json = runOptions.json ?? (extracted.json || (forced ?? (state.options.autoDetect && detectAgent(env) !== void 0)));
+	const mode = json ? "json" : "human";
+	let outBuf = "";
+	let errorCommand = program;
+	const restore = [];
+	walk(program, (cmd) => {
+		const prevOutput = cmd.configureOutput();
+		const prevHelp = cmd.configureHelp();
+		restore.push(() => {
+			cmd.configureOutput(prevOutput);
+			cmd.configureHelp(prevHelp);
+		});
+		cmd.exitOverride();
+		cmd.configureOutput({
+			...prevOutput,
+			writeOut: (s) => json ? outBuf += s : stdout.write(s),
+			writeErr: (s) => json ? void 0 : stderr.write(s),
+			outputError: (s, write) => {
+				errorCommand = cmd;
+				if (!json) write(s);
+			}
+		});
+		if (json) cmd.configureHelp({
+			...prevHelp,
+			formatHelp: (c) => JSON.stringify({
+				ok: true,
+				data: describeCommand(c)
+			}) + "\n"
+		});
+	});
+	const consoleKeys = [
+		"log",
+		"info",
+		"debug"
+	];
+	const savedConsole = consoleKeys.map((k) => console[k]);
+	if (json) for (const k of consoleKeys) console[k] = (...a) => void stderr.write(format(...a) + "\n");
+	let envelope;
+	let exitCode = EXIT.OK;
+	let printed = false;
+	try {
+		await program.parseAsync(extracted.args, { from: "user" });
+		const result = state.result;
+		const value = result?.value;
+		envelope = {
+			ok: true,
+			data: value ?? null
+		};
+		if (!json) {
+			const text = (state.options.formatHuman ?? defaultHuman)(value, result?.command ?? program);
+			if (text !== void 0) stdout.write(text + "\n");
+			printed = true;
+		}
+	} catch (err) {
+		if (err instanceof CommanderError && (err.code === "commander.helpDisplayed" || err.code === "commander.help" && err.exitCode === 0)) {
+			if (json) stdout.write(outBuf);
+			return finish({
+				ok: true,
+				data: null
+			}, EXIT.OK, true);
+		}
+		if (err instanceof CommanderError && err.code === "commander.version") {
+			envelope = {
+				ok: true,
+				data: { version: outBuf.trim() || program.version() }
+			};
+			exitCode = EXIT.OK;
+			if (!json) printed = true;
+		} else {
+			const { payload, code } = toPayload(err, program, errorCommand, state.options.describeCommand);
+			envelope = {
+				ok: false,
+				error: payload
+			};
+			exitCode = code;
+			if (!json) {
+				if (!(err instanceof CommanderError)) stderr.write(`error: ${payload.message}\n`);
+				if (payload.suggestion) stderr.write(`hint: ${payload.suggestion}\n`);
+				printed = true;
+			}
+		}
+	} finally {
+		consoleKeys.forEach((k, i) => console[k] = savedConsole[i]);
+		restore.forEach((r) => r());
+	}
+	return finish(envelope, exitCode, printed);
+	function finish(env, code, done) {
+		if (json && !done) stdout.write(JSON.stringify(env) + "\n");
+		if (runOptions.setExitCode ?? true) process.exitCode = code;
+		return {
+			mode,
+			exitCode: code,
+			envelope: env
+		};
+	}
+}
+function toPayload(err, root, at, describeName) {
+	if (err instanceof AgentError) return {
+		payload: strip({
+			code: err.code,
+			message: err.message,
+			suggestion: err.suggestion,
+			details: err.details
+		}),
+		code: err.exitCode
+	};
+	if (err instanceof CommanderError) {
+		const sub = commandPath(at).split(" ").slice(1).join(" ");
+		const suggestion = describeName ? `Run "${[
+			root.name(),
+			describeName,
+			sub
+		].filter(Boolean).join(" ")}" to see accepted arguments and options.` : `Run "${commandPath(at)} --help" to see usage.`;
+		const message = err.code === "commander.help" ? "A subcommand is required." : err.message.replace(/^error:\s*/, "");
+		return {
+			payload: {
+				code: USAGE_CODES[err.code] ?? "USAGE_ERROR",
+				message,
+				suggestion
+			},
+			code: EXIT.USAGE
+		};
+	}
+	return {
+		payload: {
+			code: "INTERNAL_ERROR",
+			message: err instanceof Error ? err.message : String(err)
+		},
+		code: EXIT.ERROR
+	};
+}
+const strip = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
+//#endregion
+export { AgentError, EXIT, agentMode, describeCommand, detectAgent, findCommand, run };

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "cli-agent-mode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Make any commander.js CLI agent-friendly: --json output envelopes, machine-readable errors with suggestions, a `describe` command that emits the CLI schema, and stable exit codes.",
+  "keywords": [
+    "cli",
+    "commander",
+    "ai-agent",
+    "llm",
+    "agent",
+    "json-output",
+    "machine-readable",
+    "claude-code",
+    "cursor",
+    "codex",
+    "mcp",
+    "exit-codes",
+    "structured-errors"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --dts --format esm,cjs && node scripts/postbuild.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "commander": ">=12"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "commander": "^14.0.3",
+    "tsdown": "^0.21.10",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/missingbits/cli-agent-mode.git"
+  },
+  "homepage": "https://github.com/missingbits/cli-agent-mode#readme",
+  "bugs": {
+    "url": "https://github.com/missingbits/cli-agent-mode/issues"
+  },
+  "author": "Gordey Levchenko (https://github.com/lgordey)",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts"
+}