Small shared primitives for the ontrack, moodle, and edstem command-line tools. The package
owns their stable command contract: verbs, error codes, exit codes, output formats, mutation
confirmation, and command self-description.
npm install https://codeload.github.com/bunizao/cli-kit/tar.gz/refs/tags/v0.1.0 commanderAfter the registry release, consumers can switch to the versioned package:
npm install @bunizao/cli-kit commanderNode.js 18 or newer is supported. Individual CLIs may require a newer runtime.
import {
commandsJson,
createProgram,
insertDefaultVerb,
mutating,
SHARED_NOUNS,
type NounSpec,
} from "@bunizao/cli-kit";
const program = createProgram({
name: "example",
version: "1.0.0",
description: "Example CLI",
});
const courses = program.command("courses").aliases(["units", "projects"]);
courses.command("list").action(listCourses);
courses.command("show <course>").action(showCourse);
const tasks = program.command("tasks");
tasks.command("list <course>").action(listTasks);
mutating(tasks.command("set <course> <task> <state>")).action(setTaskState);
const nouns: readonly NounSpec[] = [
SHARED_NOUNS.courses,
{
name: "tasks",
verbs: ["list", "set"],
defaultByArity: { 1: "list" },
valueFlags: [],
},
];
const args = insertDefaultVerb(process.argv.slice(2), nouns);
await program.parseAsync(args, { from: "user" });insertDefaultVerb accepts user arguments, not the Node executable and script prefix. It is a
pure transform and does not mutate the provided array.
Prefer parseWithPrompts over calling parseAsync yourself. It builds the program, parses,
and when a person at a terminal left out a trailing positional or a required option, asks for
it and parses again with the answer appended. moodle activities list becomes a unit picker
instead of missing required argument 'unit'. Without a terminal the usage error is thrown
unchanged, with the command's usage line and argument descriptions as its hint.
await parseWithPrompts(() => buildProgram(), args, {
ui,
fillers: {
unit: async ({ ui }) => ui.select("Which unit?", await unitChoices()),
task: async ({ provided, ui }) => ui.select("Which task?", await taskChoices(provided.unit)),
},
});A filler is looked up by argument name; without one, an argument with .choices() becomes a
picker and anything else a text prompt labelled with its description. Fillers see the
positionals typed so far, including earlier answers, so a task picker can load the chosen
unit. The factory is called once per round because Commander programs do not parse twice.
createProgram installs one help layout for the family: name and version, usage, the
commands, options, and a short "Try" list, coloured on a terminal and plain in a pipe.
--no-color, NO_COLOR and FORCE_COLOR are honoured. Group top-level commands with
helpSection the way gh does (core commands first, then the rest), add two or three
invocations with examples (text after two spaces and # renders as a comment), and
give the root a wordmark with banner; the art shows only to a person at a terminal.
helpSection(program.command("submit"), "Core commands");
examples(program, ["example units", "example submit UNIT report.pdf # asks before uploading"]);
banner(program, EXAMPLE_WORDMARK);createTheme(enabled) paints the roles every CLI's human output shares, so a person
learns once what each colour means: key (cyan) is something they can type back, such
as a unit code or task number; subject (bold) is what they gave, such as files or a
message; target (bold cyan) is where it goes; dim is a secondary fact; status
colours a word by its toneOf, the vocabulary learning sites share ("overdue" is
danger, "graded" success, "not started" muted, "announcement" accent). Pass the theme
to render and a table gets a dim header, a keyed first column and toned status
columns; pass tones for words the shared list would misread. ui.banner(art, tagline)
opens an onboarding flow with the wordmark.
isInformationalExit(error) is true for the help and version exits Commander throws under
exitOverride, including a bare noun with no verb, so the run loop can return 0 for them.
List option flags that consume a separate value in valueFlags. This lets the arity counter ignore
option values when flags are interleaved with positionals. Boolean flags and --flag=value do not
need to be listed.
resolveFormat applies explicit --json, --yaml, or --table flags, then defaults to table
for a TTY and json for a pipe. render serializes a value and can select top-level fields.
writeOutput writes to stdout or a file and treats a closed stdout pipe as successful.
Catch errors at the executable boundary and render them once:
const format = resolveFormat(program.opts(), process.stdout.isTTY === true);
try {
await program.parseAsync(args, { from: "user" });
} catch (error) {
const isNormalExit = typeof error === "object" && error && "exitCode" in error && error.exitCode === 0;
if (!isNormalExit) {
const reported = reportError(error, format);
process.stderr.write(reported.text);
process.exitCode = reported.exitCode;
}
}Commander error text is suppressed by createProgram, so the shared reporter is the only error
renderer. Help and version requests render normally, then throw Commander's zero-exit signal;
preserve that status without reporting it. Usage failures throw for the boundary to report once.
Call mutating(command) for send, submit, set, and mark-read commands. The marker is
included by commandsJson; a CLI that describes its own command tree reads it with
isMutating(command) instead of guessing from command names. Command actions call confirm before making an upstream request:
const shouldApply = await confirm(
{ summary: "Set FIT1045 task 1.1 to complete" },
{ yes: options.yes, dryRun: options.dryRun, interactive: process.stdin.isTTY === true },
);
if (!shouldApply) return;The plan and prompt are written to stderr. A non-interactive mutation without --yes throws a
usage error. A dry run prints its plan and returns false.
commandsJson(program) returns the program metadata and full command tree. Every node includes
aliases, positional arguments, options, enum values, nested commands, and mutating. Domain
commands at noun depth must use a verb exported in VERBS; unsupported verbs throw. auth and
skills are action groups rather than domain nouns and are not assigned a verb field.
A top-level command named after a shared noun's alias throws, and so does a verb that shared noun does not offer.
The exit-code table, error vocabulary, verb set, and shared nouns are public versioned API. Changing one requires a major package release.
The conformance suite is isolated under conformance/. Until all three CLIs have published their
normalized releases, missing binaries are reported as skipped tests. Its CI workflow installs the
published packages before running the suite.
SHARED_NOUNS holds the nouns every CLI names the same way. A CLI that offers one uses its spec
as is, or with fewer verbs and its own valueFlags; domain nouns such as tasks or lessons
stay with each CLI.
| Noun | Aliases | Verbs | Default by arity |
|---|---|---|---|
courses |
units, projects |
list, show, get | 0 list, 1 show |
grades |
list | 0 list, 1 list |
courses is canonical because Ed and Moodle both call them courses; units is an Australian usage.
Each grades row carries grade and max as numbers or null, and a status from
GRADE_STATUSES: graded, ungraded, unreleased (marked but not released to the student),
not_submitted, or unavailable (the platform refused or failed for that row). Display strings
such as a letter grade or a range are optional extra fields.
An Intent maps what a person says to the command and the MCP tool that answer it. One list of
intents is the single source for the skill, the MCP tool descriptions and the agent packaging:
const INTENTS: readonly Intent[] = [
{
when: "my grades / what did I get",
what: "Graded items per course with grade, max and status.",
command: "example grades [COURSE]",
tool: "list_grades",
refs: "course code, name or id",
then: "show the item for feedback",
cost: "small",
},
];
server.registerTool("list_grades", { description: toolDescription(INTENTS[0]) /* , schema */ }, handler);
const files = agentFiles({
skill: {
name: "example-cli",
description: "Reads Example courses, grades and deadlines",
useWhen: 'the user names Example or asks "what\'s due", "my grades"',
title: "Example CLI",
intents: INTENTS,
mcpServer: "example",
workflows: [{ title: "Submit an assignment", steps: ["...", "Check the submission status"] }],
program: commandsJson(program),
},
version,
repository: "https://github.com/example/example-cli",
author: { name: "example" },
mcpServers: { example: { command: "npx", args: ["-y", "example-cli", "mcp"] } },
});
writeAgentFiles(process.cwd(), files); // { check: true } returns stale paths for CIagentFiles returns, by path from the repository root:
skills/<name>/SKILL.md, whichnpx skills add owner/repoand Claude Code both find. An agent loads it whole, so it stays short: one table of what the user says against the CLI command and theserver:toolMCP tool, the workflows as copyable checklists, the rules and the setup. A CLI with a mutating command gets the shared dry-run, confirm, apply, read-back workflow first. Each tool's full description stays with the MCP server.- The frontmatter description is
descriptionthen "Use whenuseWhen".renderSkillthrows when the name or description breaks the Agent Skills limits (lowercase hyphenated name, 1024 characters, no<or>) or uses "I" or "you" outside quotes. skills/<name>/references/commands.md: every command with its arguments, options and whether it mutates, plus the exit codes. Pages inreferencesare written next to it.skills/<name>/agents/openai.yaml, whenopenaimetadata is given..claude-plugin/plugin.jsonand.claude-plugin/marketplace.json: the repository is a Claude Code plugin, which loadsskills/by default, and its own marketplace. Install withclaude plugin marketplace add owner/repo, thenclaude plugin install example-cli@example-cli. A repository with a rootCLAUDE.mdgets one validator warning, since that file is not plugin context;claude plugin validate .passes,--strictdoes not.
writeAgentFiles never deletes, so a CLI moving to this layout removes its old root SKILL.md,
references/ and agents/ itself.
An MCP server that runs on Cloudflare Workers imports toolDescription from
@bunizao/cli-kit/intents, which pulls in neither commander nor Node builtins.
checkIntentCommands(program, nouns, intents) throws when an intent's command no longer parses:
a renamed noun or verb, a removed option, or the wrong binary name. Call it from the CLI's tests
so the skill and the MCP descriptions cannot drift from the command tree.
evals/trigger.mjs checks whether the descriptions route requests to the right skill. It puts
every sibling skill in one Codex workspace, so they compete as they do for a student who has all
three installed. A skill that steals its sibling's requests looks like the sibling undertriggering
when either is tested alone. For each query it records which skills/<name>/ Codex opens first.
node evals/trigger.mjs \
--skill ../moodle-cli/skills/moodle-cli \
--skill ../ontrack-cli/skills/ontrack-cli \
--skill ../edstem-cli/skills/edstem-cli \
--runs 3- The folder name is the skill name.
--pooldefaults toevals/trigger-pool.json: 29 requests, each with the skill it should reach ornone.--modeldefaults to Codex's configured model.--outkeeps every run's pick and first command. - Each Codex run is killed at its first command, and each skill's binary (
moodle,ontrack,edstem) is a failing stub first onPATH, so nothing reaches a real account.HOMEis a temporary folder that hides the user's own skills;CODEX_HOMEkeeps the sign-in. - A run costs about 16k input tokens, so the default 29 × 3 is about 1.4M. Results move by about one run per query between passes, so compare changes across three runs, not one.
- This measures Codex, not Claude. Claude Code reads the same folder layout and frontmatter, but its routing can differ.
createUi gives every CLI the same interactive surface, drawn with @clack/prompts on
stderr so --json output on stdout stays clean. It only prompts when both stdin and the
output are terminals; in a pipe, log calls print plain completed lines, spinners print
their outcome, and every prompt throws a usage error that says what to pass instead.
const ui = createUi();
ui.intro("moodle submit");
const unit = await ui.select("Which unit?", candidates.map((c) => ({ value: c.id, label: c.name, hint: c.code })));
const spin = ui.spinner();
spin.start("Uploading 2 files");
spin.stop("Uploaded 2 files");
ui.outro("Done");select switches to type-to-filter above AUTOCOMPLETE_FROM choices, or always with
{ search: true }; every typed word must appear in the label or hint, in any order.
{ initial } highlights a row. A multi-step picker passes { back: true } and gets BACK
when the person presses Escape. Ctrl+C inside a prompt throws a cancelled error (exit 130). confirm(plan, options) is built on the same
layer and keeps its contract: --dry-run prints the plan, --yes skips the question, a pipe
without --yes is a usage error.
detectAudience({ stdin, stdout, env, format }) returns "human" only for a person at a
terminal reading a table: both streams are TTYs, the format is not JSON or YAML, and none
of AGENT_ENV_VARS (CLI_AGENT, CLAUDECODE, CI) is set. Everyone else is an agent and
gets machine output, no prompts, and errors that name the flag to pass. createUi applies
the same environment rule on its own, so an agent that allocates a pty still never sees a
prompt. Agents that run commands in a terminal should export CLI_AGENT=1.
ui.password masks a secret; without a terminal it throws so the caller can point at a
--token-stdin style flag instead. ui.editor collects several lines in $VISUAL or
$EDITOR the way git collects a commit message, and throws without a terminal so the
caller can point at a --body-file style flag.