# ax-command One definition of a command: its words, effect, arguments and flags, examples and output. From it come the parser (whose refusals name the exact fix), the usage and help, `help --json` and the MCP tool's input schema, so the CLI and the MCP server can never disagree. ```sh npx shadcn@latest add ourostack/ouro-ui/ax-command#v1.3.10 ``` It installs `lib/ouro/ax/command.ts`, with `ax-effects`, `ax-exit-codes`, `ax-outcome`, `ax-problem`, `ax-voice`, `ax-wait`. Its tests are `ax-command-tests`. Every item runs on Node 22.18 or later as it is copied: the files import each other as `./.ts`. The [Ouro AX guide](ax.md) shows how they fit together. ## Exports ### `AGENT_FLAG` The flag a self-scoped command takes: who is calling. The kit compares it with the item's owner, so an agent acts on its own item only. ```ts const AGENT_FLAG: FlagSpec ``` ### `ArgSpec` ```ts interface ArgSpec { name: string; description: string; required?: boolean; rest?: boolean | "list"; stdin?: boolean; unless?: string | readonly string[]; source?: string; missing?: string; values?: readonly string[]; } ``` ### `argUsage` ``, `[]` or ``, as usage shows an argument. ```ts function argUsage(a: ArgSpec): string ``` ### `BUILTIN_FLAGS` ```ts const BUILTIN_FLAGS: Readonly> ``` ### `checkInput` Checks an MCP call's arguments against the command, as the parser checks argv: an unknown property names the nearest, a wrong type or a missing value names it. The fix is the arguments to send instead, as JSON. ```ts function checkInput(cli: Cli, cmd: CommandDef, raw: unknown, thing?: string): Readonly> ``` ### `checkOwner` Refuses a self-scoped call on an item that is not the calling agent's (`not-yours`, the usage exit): it names whose item it is and who called, and gives the command for the caller's own item (`self.instead`) or says to ask the person. It passes a command without `self`, and the owner's own call. runCli, dispatch and the MCP server call it before plan() or run(); a tool that runs commands its own way calls it too. ```ts function checkOwner(cli: Cli, cmd: CommandDef, input: Readonly>, ctx: C) => Promise ``` ### `Cli` ```ts interface Cli { readonly name: string; readonly about: readonly string[]; readonly commands: readonly CommandDef[]; readonly exits: ExitTable; readonly headings: EffectHeadings; readonly globalFlags: Readonly>; readonly ambiguous: Readonly>; readonly personOnly: Readonly>; readonly groups: Readonly>; readonly outcomeExits: OutcomeExits; readonly waitExits: WaitExits; readonly voice: VoiceDef; } ``` ### `CliDef` ```ts interface CliDef { name: string; about: readonly string[]; commands: readonly CommandDef[]; exits?: ExitTable; headings?: EffectHeadings; globalFlags?: Readonly>; ambiguous?: Readonly>; personOnly?: Readonly>; groups?: Readonly>; outcomeExits?: OutcomeExits; waitExits?: WaitExits; voice?: VoiceDef; } ``` ### `CommandDef` A command's definition. `C` is the context run() and plan() get: RunContext, or an adopter's own that extends it. ```ts interface CommandDef { name: string; aliases?: readonly string[]; summary: string; effect: Effect; readOnly?: boolean; why?: "required" | "optional" | "none"; args?: readonly ArgSpec[]; flags?: Readonly>; examples?: readonly string[]; output?: string; hidden?: boolean; summarizes?: boolean; loose?: boolean; self?: SelfScope; run?(input: Input, ctx: C): R | Promise; plan?(input: Input, ctx: C): Outcome | Promise; text?(result: R, input: Input): string; } ``` ### `defineCli` Builds the tool and checks its definitions: unique names, a valid exit table, examples that parse. ```ts function defineCli(def: CliDef) => Cli ``` ### `defineCommand` ```ts function defineCommand(def: CommandDef) => CommandDef ``` ### `exampleArgv` An example's words after the tool's name, up to a pipe; null when the tool is not in it. ```ts function exampleArgv(tool: string, example: string): string[] | null ``` ### `findCommand` The command the leading words name (the longest match), and how many words it took. ```ts function findCommand(cli: Pick, "commands">, words: readonly string[]): { command: CommandDef; used: number; } | null ``` ### `flagsOf` The flags a command takes: the built-ins, the tool's, --why where asked for, --dry-run on an "others" command, then its own; a command's own flag replaces a generated one of the same name, except a self-scoped command's `--agent`, which the owner check needs. ```ts function flagsOf(cli: Pick, "globalFlags">, cmd: CommandDef): Record ``` ### `FlagSpec` ```ts interface FlagSpec { type: FlagType; description: string; required?: boolean; placeholder?: string; values?: readonly string[]; min?: number; max?: number; stdin?: boolean; unless?: string | readonly string[]; sensitive?: boolean; } ``` ### `FlagType` One definition of a command: its words, effect, arguments and flags, examples and output. From it come the parser (whose refusals name the exact fix), the usage and help, `help --json` and the MCP tool's input schema, so the CLI and the MCP server can never disagree. ```ts type FlagType = "boolean" | "string" | "number" | "enum" | "list"; ``` ### `flagUsage` `--name `, or `--name` for a boolean. ```ts function flagUsage(name: string, spec: FlagSpec): string ``` ### `HelpAsked` ```ts interface HelpAsked { kind: "help"; topic: string | undefined; json: boolean; } ``` ### `Input` ```ts type Input = Readonly>; ``` ### `inputSchema` The command's input as a JSON Schema: its arguments and flags as properties (the MCP tool's inputSchema). ```ts function inputSchema(cli: Pick, "globalFlags">, cmd: CommandDef): JsonSchema & { properties: Record; required: string[]; } ``` ### `InputValue` ```ts type InputValue = string | number | boolean | readonly string[]; ``` ### `JsonSchema` A JSON Schema object, as an MCP tool's inputSchema takes. ```ts interface JsonSchema { type?: string; description?: string; enum?: readonly string[]; items?: JsonSchema; minimum?: number; maximum?: number; properties?: Record; required?: string[]; additionalProperties?: boolean; } ``` ### `Meaning` One meaning of an ambiguous word, and the command for it. `use` may hold `{args}`, the words the agent gave after the ambiguous word in that command's argument slots (a slot with none shows its placeholder), and `{flags}`, the flags the agent gave that the command takes (a sensitive value as its placeholder). A flag `use` writes out itself, such as `--why `, gives way to the same flag given. ```ts interface Meaning { means: string; use: string; } ``` ### `parse` Parses argv against the definitions. Throws an AxError (exit "usage") whose fix is the corrected command line: an unknown flag names the nearest one, a missing argument shows where it goes and where to get it, a missing --why is appended, an ambiguous word lists each meaning's command. ```ts function parse(cli: Cli, argv: readonly string[]): Parsed | HelpAsked ``` ### `Parsed` ```ts interface Parsed { kind: "run"; command: CommandDef; input: Input; json: boolean; unchecked: Readonly>; } ``` ### `PersonOnly` Words only the person acts on, such as `unmute`: the reason, one sentence to you, the agent ("You can't turn on the person's microphone; only they can."), and how the person does it (`with the microphone button in the call's controls`). The words refuse, `refused`, with both in one line, and `help --json` lists them under `personOnly`, so an agent learns them before it tries. ```ts interface PersonOnly { reason: string; how: string; } ``` ### `RunContext` ```ts interface RunContext { stdin(): Promise; json: boolean; } ``` ### `SelfScope` A command an agent may run only on its own item, such as its own row in the person's list of listening agents (the twin of a component action declared `scope: "self"`). The command takes `--agent `, and the kit asks `owner` whose item the call names, before plan() or run(): when it is not the calling agent's, the call is refused (`not-yours`) and nothing runs. `help --json` marks the command `scope: "self"`. ```ts interface SelfScope { owner(input: Input, ctx: C): string | null | Promise; instead?: string; } ``` ### `toArgv` The argv that runs a command with this input, the way an agent would type it; the first stdin-capable argument's text goes on stdin ("-"), so text that starts with "-" or spans lines passes whole. ```ts function toArgv(cli: Pick, "globalFlags">, cmd: CommandDef, input: Readonly>): { argv: string[]; stdin: string | null; } ``` ### `usageOf` The command's usage line from its definition: words, arguments, required flags, then the optional ones. ```ts function usageOf(cli: Pick, "globalFlags">, cmd: CommandDef): string ```