Crust logoCrust

Schema

Describe commands as JSON Schema and Markdown for agents and tools.

schema() serves agents that discover commands on demand from a shell; how agents use your CLI shows where it fits beside skills and MCP.

Usage

cli.ts
import { Crust, defineCommand } from "@crustjs/core";
import { schema } from "@crustjs/extensions";
import { z } from "zod";

const app = new Crust("my-cli").extend(schema()).add(
	defineCommand("deploy", { description: "Deploy the app" }, (cmd) =>
		cmd
			.args({ name: "target", type: "string", required: true, choices: ["staging", "prod"] })
			.output(z.object({ id: z.string() }))
			.action(({ args }) => ({ id: `dep_${args.target}` })),
	),
);

await app.execute();
$ my-cli schema deploy
{"input":{"type":"object","properties":{"target":{"type":"string","enum":["staging","prod"]},"raw":{…}},"required":["target"]},"output":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object",…}}

$ my-cli --llms
# my-cli
…

schema() adds a schema [path...] command and a root-only boolean --llms flag.

schema [path...]

Prints one line of JSON describing the command at path, or the root command when path is omitted:

  • input: the JSON Schema of the command's arguments and flags as one flat object, from commandInputSchema(). This is the object input()'s --input and the MCP server accept.
  • output: the draft 2020-12 JSON Schema of the result, from the command's .output() schema. It is omitted when the command has no .output() or its schema cannot produce JSON Schema (see standardJsonSchema()), rather than replaced by an empty {} schema; a converter's own result is printed as is.

Path segments are canonical command names or aliases, like routing; hidden commands resolve too. An unknown segment fails with a COMMAND_NOT_FOUND error naming the path up to it, such as Unknown command "remote ad".; didYouMean() presents it like any unknown command.

The command also returns the object, so run() gets it as the outcome's result:

const outcome = await app.run(["schema"], { args: { path: ["deploy"] } });

Standard Schema–backed arguments and flags are described by their schema's input JSON Schema when run() accepts that shape, and by their token type otherwise; see the MCP input mapping.

--llms

Prints a compact Markdown index of every visible command. Each command gets:

  • a ## heading with its usage line, then its description;
  • its arguments and flags with their types, descriptions, defaults, choices, and environment variables;
  • its documentation sections as ### headings, except those with except: [schema] or an only list without schema.

Hidden commands are left out. --llms takes over the invocation like --help. It is root-only, so my-cli deploy --llms is an unknown flag.

On this page