draftty
v0.1.0
Published
Design CLIs in plain text before you build them. A YAML spec, a live terminal simulator, generated docs, and design checks.
Downloads
92
Maintainers
Readme
draftty
Design CLIs in plain text before you build them.
You write a YAML file describing what a CLI says: commands, help, output in each situation, and what --json returns. draftty turns it into:
- try: a prompt and one screen. Type a command and see the designed output. The command's scenarios (
default · empty · not-found) and--jsonswitch the screen. Help, usage errors, "did you mean", and tab completion are generated. - docs: generated reference: every command with its arguments and options, the JSON and exit-code contract, and an example for each.
- check: design checks for inconsistent verbs and flags, missing empty states, json gaps, and hints on stdout.
It works for a whole CLI or one part of one. It's built to be written by agents and reviewed by people, side by side.
Install
Needs Node.js 20 or later.
npm i -g draftty # then: draftty <command>
npx draftty init # or without installingQuick start
In the project you're designing:
draftty init mycli # design/mycli.yaml, design/AGENTS.md for your agent, .draftty/ in .gitignore
draftty dev # browser: try, docs, check; reloads as you (or your agent) editDesigns live in design/, one YAML file each. Every command finds them there (--spec overrides), and .draftty/ holds local state.
Working with an agent
draftty init writes design/AGENTS.md (and a CLAUDE.md that imports it), so any coding agent picks up this loop:
draftty dev, once, in the background. It reloads on every save and prints whatcheckfinds.- Edit the YAML.
draftty check --fix: formats, updates handler types, and reports design issues. Exit 1 on errors.draftty run <command>: stdout, stderr and exit code exactly as designed.
draftty skill prints the agent skill: the workflow and the full spec reference.
Commands
| Command | What it does |
|---|---|
| init [name] | Start a design in ./design, with a brief for your agent |
| dev [path] | Serve designs with a live terminal, docs, and checks |
| build [path] --out <dir> | Write the designs as a static site you can host anywhere |
| publish, pull | Share a draft through a draftty platform, and bring one back |
| check [path] | Design checks, and drift between examples and handlers |
| docs [path] | Print generated docs as Markdown |
| types [path] | Generate TypeScript types for handlers from the spec |
| run [design] <command...> | Run one command against a design |
| use [design] | Make the design's binary (e.g. todo) run this design |
| shell [design] | Open a shell where the design is a real binary, with fresh data |
| reset [design] | Put a design's data back to its seed |
| skill | Print the agent skill (SKILL.md) |
draftty <command> --help has the details.
The spec
name: vercel
title: observability
commands:
drains:
summary: Send logs to external services
commands:
ls:
summary: List drains
scenarios:
default:
run: vercel drains ls
out: |
{dim}id name status{/}
drn_k2l9 datadog {green}● healthy{/}
json: [{ id: drn_k2l9, name: datadog, status: healthy }]
empty:
run: vercel drains ls
err: "{dim}No drains yet. Add one with `vercel drains add <url>`.{/}"
json: []Output is written literally, because the wording is the design. Text output and --json sit side by side as two contracts for the same situation. {{arg}} placeholders fill in what the user typed. A variant extends: a design and only writes what differs. The full reference is in draftty skill.
Handlers and data
When a design has to work (filters that filter, add followed by ls), give it handlers: a TypeScript module that answers commands over plain JSON data.
name: todo
handlers: ./todo.ts # optional; commands without a handler use scenarios
data: ./fixtures.json # { "todos": [ … ] }: the starting data
now: 2026-10-06T14:00:00Z # a fixed clock, so runs are reproducible
commands:
ls: { summary: List open todos, flags: { tag: { value: tag } } }import { table } from "draftty/handler";
import { defineHandlers } from "./todo.types"; // generated by `draftty types`
export default defineHandlers({
ls: ({ flags, data, out }) => {
const rows = data.todos.filter((t) => !t.done && (!flags.tag || t.tags.includes(flags.tag)));
out(table(rows, ["id", "title"]));
return { json: rows }; // what --json prints
},
});Handlers are bundled into one browser module, which is what runs in draftty run and in the browser alike. So they can't use Node APIs, and they import only the design's own files and draftty/handler. The YAML still owns the surface: draftty parses and validates first, so the handler only sees valid input. With handlers, scenarios become examples, and check flags drift between them.
Share it
draftty build design/ --out site # a static site: then `npx serve site`, or put it on any static hostLicense
MIT
