@ultimat3/cli

@ultimat3/cli

The x binary. One char during dev, one command per job, --json on every one of them.

What it owns

Commands and the x verify step count, As of 2026-08:

Command	Does	Notes
x new <name>	scaffolds the monorepo	interactive-free; auth, seeded DB, example route
x dev	every role in one process	embedded Postgres/events/storage, /_x mounted
x build --target docker|binary|static	one artifact	ROLE selects behaviour at start
x verify	the gate	19 named steps, each with pass/fail + duration
x g <primitive> <name>	scaffolds a primitive with a passing test	never a TODO stub
x db gen|migrate|reset|branch|backfill	everything DB	branch = copy-on-write clone + preview URL; backfill dry-runs unless --write. x db studio is planned — it parses, and exits X_NOT_IMPLEMENTED naming /_x's db panel
x mcp serve	@ultimat3/mcp's 13 dev tools, over stdio or HTTP	one catalog, one scope set, both transports
x doctor	environment, ports, drift, PWA prerequisites	every finding carries a fix command
x deploy	container deploy plan	compose or helm; zero platform primitives
x manifest / x routes	generated facts	x.manifest.json, openapi.json, route table
x actions / x queries / x entities	the declaration registries	list and describe <name>, straight off the registries
x tasks list|show	cron tasks	timezone and next run, off registeredTasks()
x jobs ls|show|retry|cancel|drain	the queue	depth, dead letters, step traces, retry --from-step, cancel --reason, drain --to
x test [type]	one of the six test types, or all	same type rule as the gate; --filter, --sample N
x env check|example	the typed environment envSchema declares	and the .env.example rendered from it
x secrets show|init|edit|set|rotate	the committed encrypted secrets	decrypted into the envSchema variables of the same names
x policy list|explain <subject>	which clause decided a permission, and why	five packages print x policy explain as a denial's fix:
x i18n check|add|sync	catalogs: gaps, a new locale, key sync	all three of i18n's own error fixes name it
x errors explain <CODE> / list	the error table, programmatically	refuses an unregistered code instead of inventing one
x docs "<question>"	the framework docs, offline	answered from the installed packages, never the network
x fix boundary <file>	the minimal cut for a crossed surface boundary	prints the plan and the git mv; never rewrites a file

Everything in CLI reference's planned table is also in the registry and exits X_NOT_IMPLEMENTED with a fix: naming the closest shipped command — "not built yet" and "not a command" are different facts.

The output contract

Every command returns one CommandResult; the human renderer and the JSON renderer are projections of it, so --json can never drift from the terminal.

X_DB_DRIFT: schema differs from migrations
  cause: table "posts" has column "publish_at" not present in any migration
  fix:   x db gen "add publish_at"

x verify --json
# {"ok":false,"command":"verify","summary":"1 of 19 steps failed","steps":[...]}

x verify steps

typecheck lint boundaries filesize package-shape errors unit contract live job e2e eval drift contract-diff budgets seo i18n manifest roadmap

Nineteen, in cost order, defined once as VERIFY_STEP_NAMES (verify-step.ts) — the summary count above is projected from that list, and the framework repo's own gate (bun run verify) runs exactly it. A step with nothing to check here reports as skipped, never as passed. Never bails early: an agent fixing three things needs all three findings from one run.

--only <step> runs one step, for an iteration loop — it prints NOT A GATE RUN in the human summary and in --json (data.notAGateRun), and it writes no floor file. The gate is this command with no flag, which is what "one command means shippable" means. There is no --skip: a knob that removes a step from a run that still calls itself the gate is the one thing this command must not offer. The exit code is non-zero if any step fails.

A committed x.verify.json is the floor, As of 2026-08: it names the steps this repo has already proved it can run, and a step it names that reports nothing is X_VERIFY_SUITE_VANISHED rather than a skip. "Nothing" is both ways a suite disappears — no files at all, and every test in the files it found skipping itself, which is read back out of bun test's own summary. x new writes one.

An app extends the gate with its own conventions, never with its own step: a file in guards/ exports a guard whose check(root) returns Finding[], and the boundaries step runs every one of them. Nothing registers a guard — the directory is the registration — and what a guard returns is held to the same error contract shipped source is (X_GUARD_INVALID, X_GUARD_FAILED, X_GUARD_FINDING_INVALID). x g guard <name> scaffolds one with its test.

Layout

File	Responsibility
bin.ts	argv, stdout, exit code — nothing else
write-line.ts	the synchronous fd-1 write both published entry points use (create-ultimate's too)
dispatch.ts	parse → run → render → exit; the only I/O boundary
parse.ts	flags, subcommands, --json, --help, suggestions
flag-number.ts	the one integer-flag reader — --port, --workers, --shard
shell-quote.ts	the one POSIX quoter for a value pasted into a fix: or a reproduce line
output.ts	one data shape, two renderers, the 3-line error format
registry.ts	the one command list
generate-kinds.ts	which generators exist, and how a command line names one
guards.ts	the app's own conventions: guards/ discovered, run, and held to the error contract
cmd-*.ts	one command group each
templates/	scaffolding as typed string modules, not copied fixtures
app-load.ts	import an app's modules so the framework registries hold it
app-manifest.ts	x.manifest.json, projected by @ultimat3/manifest
app-openapi.ts	openapi.json, projected by @ultimat3/action
app-boundaries.ts	app import boundaries, over @ultimat3/render's surface check
app-agents-md.ts	AGENTS.md exists and stays short, over @ultimat3/manifest's check
serve.ts	what a container starts — runRole(options), the same boot x dev runs minus the watcher, /_x and dev: true. x new's apps/web/server.ts is three lines that call it
prerender.ts	x build --target static: which site/ routes qualify, and where the bytes land
metrics-endpoint.ts	the METRICS_PATH scrape listener every role opens, on METRICS_PORT
otlp-export.ts	the exporters OTEL_EXPORTER_OTLP_ENDPOINT switches on, and their drain hooks
dev-*.ts	what x dev boots: services, runtime, routes, hooks, roles, the /_x mount
island-bundle.ts	every *.island.tsx built as its own entry point, content-hashed
island-routes.ts	the one route those chunks are served from, in dev and in the container
mcp-host.ts	the shell-side half of @ultimat3/mcp's dev server — db, tests, logs, verify
verify-step.ts	the step shape, the step names, the host-check hook
verify-tests.ts	one bun test invocation per test type
workspace-checks.ts	file-size ceiling and package contract files
drift.ts budgets.ts	the checks x verify composes

The CLI describes an app by loading it, never by parsing it: action(), entity(), job() and defineRoute() register themselves, and x manifest, x routes and x verify read the same tables the running server reads. There is no second definition of a primitive, no second OpenAPI builder and no second surface-boundary walk anywhere in this package.

Generated file layout

x g writes into the feature slice:

apps/web/app/<feature>/{entity,repo,service,policy,errors,ui}.ts
apps/web/app/<feature>/{actions,queries,live,jobs,tasks}/<name>.ts
apps/web/{site,app}/<path>/page.tsx
apps/web/{site,app}/<path>/<name>.island.tsx     # x g island <name> --at <dir>
apps/admin/src/pages/<name>.tsx                  # x g admin:page <name> --permission p
guards/<name>.ts                                 # x g guard <name>

Every emitted source has a <file>.test.ts beside it that passes on the first run.

Errors

X_CLI_UNKNOWN_COMMAND X_CLI_BAD_FLAG X_VERIFY_FAILED X_NOT_IN_APP X_BUN_VERSION X_NOT_IMPLEMENTED X_GUARD_INVALID X_GUARD_FAILED X_GUARD_FINDING_INVALID