An open source design system that's fully customizable and agent ready
CLI conventions for contributors
This guide turns the CLI surface architecture (docs/architecture/cli-surface.md)
and the admission rules (docs/specs/AST-042-cli-command-admission/spec.md) into
the steps you follow when you change packages/cli. It does not create policy.
Where it disagrees with either record, the record wins.
Who the CLI is for
The caller is an agent. It runs the CLI in a subprocess, reads --json, and
acts on the result without a person watching. A person reading the text output
is a supported reader, never the caller the design serves.
Two things follow, and they settle most arguments before they start:
- The CLI must not impede the agent's flow. No prompt, no confirmation, no question. A command that cannot finish returns an error with a code the agent can branch on and a suggestion it can act on.
- The output is data first.
--jsonis the source of truth. The text output is a projection of the same values, produced by the formatters.
What the CLI is for
Give an agent access to everything that helps it build with Astryx: what components and templates exist, what they do, how they are used, what is wrong with the code in front of it, and the utilities that change that code.
The measure of the CLI is coverage and depth of that surface, not the number of commands on it. Most valuable work makes an existing command answer better.
Adding a command
The bar depends on the tier (spec:AST-042 FR4):
- A new top-level command needs a current system spec that authorizes it,
approved by an approval owner (an owner listed in the knowledge schema's
approvalOwners). Write the spec first. - A new subcommand stays inside its parent's one job. State its case in the
pull request, and get approval from a code owner of
packages/cli..github/CODEOWNERSis the source of truth for who that is. - A new flag follows the flag rules below and needs no extra approval.
Propose a command before you write it: a command is a permanent concept — it appears in help, in the manifest, in the README, and in every agent's cheat sheet, and removing one is a breaking change.
Every command is a thin layer over one exported api/ function: parse the
arguments, call the function, render the result. The function does the work, so
an agent that scripts the API gets the same result as one that runs the command.
A command earns its place when all four hold:
- It answers a question an agent actually has while building with Astryx — not a function the CLI happens to be able to expose.
- No existing command can be deepened to answer it. Deepening is the default. Reach for a new command only after naming the command you would have extended and saying why extending it is wrong.
- It is one job. If the summary needs an "and", it is two commands.
- Its result is worth returning as data. If the useful output is prose for a person, it is a docs topic, not a command.
A command that fails any of these is usually a flag, a subcommand, or a docs topic.
Adding a flag
Flags are more forgiving than commands, and they do not need a proposal, but
spec:AST-042 FR5 makes the rules below binding. They are not free: every flag
is a branch an agent has to know about, and a combination somebody has to keep
working.
A good flag:
- Narrows or redirects work the command already does. It never gives the command a second job.
- Has a default that is the right answer most of the time. A flag exists to escape the default, not to reach the useful behaviour. If callers must pass it to get a sensible result, the default is wrong.
- Is boolean-off or has a value. A boolean flag that defaults to true is a mis-named opt-out; name the opt-out instead.
- Changes what the command produces. A flag that only changes how the same
result is presented belongs to the global set (
--json,--detail,--lang), not to your command. - Is not a workaround. If the flag exists so callers can avoid a defect, fix the defect.
- Has a closed composition matrix. See below — this is the check people skip.
If the flag changes what the command is, it is a subcommand.
The composition matrix
Before you land a flag, pair it with every flag already on that command and decide each cell. There are only three legal answers, and every cell needs one:
- They compose — and a test proves it.
- They are refused together — with a clear message and a code.
- They cannot co-occur — because another rule already refuses the combination that would reach them.
An undecided cell is the defect. It ships as behaviour nobody chose, and an agent finds it before a person does.
Flags with the same name
A name is a promise across the whole CLI. Two rules:
- The same flag name means the same thing everywhere, and is spelled the same way. Nothing else may take a flag name for another idea.
- No command is forced to carry a flag because a sibling has it. Alignment is on meaning, not on presence.
Where the code goes
Copy api/blog and clients/cli/commands/blog.mjs. They are the reference
layout (cli-surface INV20–INV22).
- The behavior lives in
api/<subject>/: an entry<subject>.mjs, one leaf folder per operation, aFunctionDocand typedefs for each exported function, and tests beside the code they cover. - Anything that touches the environment — files, the network, subprocesses,
loading the project or running discovery — goes in the subject's
_adapter.mjs. The leaves only shape the result. - The handler in
clients/cli/commands/only parses, calls, and renders.
Output: use the shared functions
Never call console.log. Every path is provided:
| You want | Use |
|---|---|
| A machine result | jsonOut({type, data, meta?}) |
| An error | jsonError(message, suggestions, code) / AstryxError |
| A heading, prose, a list | section(), text(), list() |
| One record, or many | record(obj, opts), records(arr, opts) |
| A code sample | code(source) |
| To print any of the above | emit(...blocks) |
| Chatter that JSON must hide | humanLog(), humanWarn() |
emit accepts only a renderer-produced Block, so a bare string will not
compile. Keep text field names identical to the JSON keys — the text output is
a view of the envelope, not a separate design. Do not pad strings, align
columns, or draw tables yourself; map rows onto records(). A new block kind
needs the evidence that spec:AST-042 FR3 asks for.
Errors: every failure carries a code
Add a code to foundation/response/error-codes.mjs when no existing one fits.
Codes are ERR_<SUBJECT>[_<QUALIFIER>], grouped by subject, and append-only:
once shipped, a code is never removed and never re-meant. Reword the message
whenever it helps a reader; never make a caller match on it.
Attach suggestions where the agent has an obvious next move — a near-miss
name, the command that lists valid values.
Every command ships a doc
A command is not done without its CommandDoc in <name>.doc.mjs. Fill in
summary, description, args, options (each with a description),
examples, exitCodes, related, and outsideProject: what the command does
outside a project. Help text, the README tables, and the
manifest are generated from it, so an undocumented flag is an invisible flag.
Give at least one example that an agent would actually run, including a --json
one.
Global mode: every command works outside a project
People install the CLI once for their computer and run it in any folder
(spec:AST-081). So every command also has to work, or explain itself, in a
folder that is not a project, and its docs have to say which.
- Declare
outsideProjectin the command doc:same(it answers as it would in a new project),refuse(it writes nothing and fails before doing any work, naming what it needs), orown(it does something else). A command that only groups subcommands declares nothing.clients/cli/commands/outside-project.test.mjsruns every command in an empty folder and checks what it does against this value, and fails on a command without one; anowncommand needs a test of its own there. - Add the note, for readers. Every
refuseand everyowncommand carries one prose note that startsIn global mode:, says exactly what it does outside a project (the error code and message it stops with, or what it does instead), and links{@link namespace:global}.test/global-mode-notes.test.mjsfails on a missing note, andtest/global-mode-docs.test.mjschecks that the error code a note names is the one the command stops with. An API function whose result depends oncwdbeing in a project carries the same sentence in its description. - Add a who-answers row when a change touches which copy of the CLI
answers (an install layout, a door, a hand-off rule): one row in the global
and project table of
spec:AST-081and its test inpackages/cli/test/global-local.test.mjs, named with the row's number (G12 …); a test there fails on a gap in the row numbers. - Quote, never paraphrase, what the CLI prints. A terminal line shown on a
global-mode page must be one the CLI prints;
test/global-mode-docs.test.mjsbuilds those lines from the CLI's own strings.
The user-facing explanation lives in astryx docs global.
Every integration item ships a typed doc
A discoverable contribution is not done without a strongly typed
<source-stem>.doc.mjs beside its source or payload. Export the descriptor type
from @astryxdesign/cli/authoring, annotate the descriptor with that type, and
use the kind's canonical typed export. New descriptor kinds use the stamped
default export. The descriptor is the only place for item metadata. The root
integration manifest points at directories; it does not enumerate the items
inside them.
When an item spans several files, define one confined item-local ownership boundary and make discovery, materialization, and pack verification enumerate the same complete set. Never repeat source identity in the descriptor when the same-stem pair proves it.
Never catalog items centrally, for any kind: no file under a root that lists its
items (like themes/manifest.json), and no per-item map or list in the
integration manifest (like a map of template replacements). Per-item options
such as replaces go in the item's own .doc.mjs. Adding one item changes no
file its siblings share, apart from declaring a new root. 0.6 shipped a theme
catalog and had to remove it as a breaking change; do not repeat it.
Released alternate readers may remain for compatibility, but new writers,
examples, and contribution kinds use .doc.mjs. See spec:AST-039 for the
compatibility transition and the mandatory theme descriptor contract.
Marking work in progress
Some of the surface is not finished, and today nothing on it says so. Callers cannot tell a settled command from one still being shaped.
When you land a command or subcommand that is not ready to be depended on, mark it, and say in the doc what is still expected to change. Treat an unmarked command as stable: changing its output shape or its flags is then a breaking change.
Checklist before you open the pull request
- For a new top-level command: a current spec authorizes it. For a new subcommand: a code owner approved its case.
- The handler only parses, calls one exported
api/function, and renders; the subject's adapter does any file, network, or project access. - One file per command, with its sibling doc file.
- Every new integration item has a typed, same-stem
.doc.mjs; the root manifest only locates its directory. No catalog file, no per-item map. -
--jsonreturns one envelope; thetypematches the API function. - Every failure path carries a code; new codes are appended, never edited.
- No
console.log; all human output goes through the formatters, with no hand-padded columns. - Text field names match the JSON keys.
- Exit code is the same with and without
--json. - The composition matrix is closed: every pair composes with a test, is refused with a message, or cannot co-occur.
- Any path you write passes through
assertWithin. - The doc lists the new flag, an example, and the exit codes.
- The doc declares
outsideProject(same,refuse, orown), and a test run outside a project matches it. - Marked as work in progress if it is not ready to be depended on.
- The command doc declares
outsideProject; a value other thansamehas itsIn global mode:note and a test of what it does outside a project.
Common review smells
- An item catalog below an integration root, or a per-item map in the
manifest. Put metadata and options in the typed, same-stem
.doc.mjs; the root manifest points at the directory. - A flag that only a maintainer would pass. It is a debugging affordance; keep it out of the surface.
- A new command whose summary contains "and". Two commands.
- A handler that reads files or loads the project. That work belongs in the API subject's adapter.
- A flag added because another command has one. Presence does not have to align; meaning does.
- A composition cell nobody decided. The most common defect in a flag PR.
- A code invented at the call site. Codes live in one frozen table.
- Text output built with string concatenation. It will drift from the JSON within one release.
--jsonoutput that omits what the text output shows. The text is the projection; it cannot be the richer of the two.- An error message that tells the agent to "check your configuration". Name the file, the key, and the expected value, or give a suggestion.
- A flag whose default is the unhelpful answer. Agents will not discover it.