@avelon/cli

@avelon/cli is reeve, the official who administers an Avelon app. It is an Ink TUI on Bun that also stays fully scriptable. Reach for it to generate the application tree, sync the Next router, run Bailiff, drain errands, and ask doctor whether a push is safe.

Bare ./reeve opens the TUI. Any subcommand with arguments skips it. --no-tui and a non-TTY stdout force plain mode.

Installation

bun add -d @avelon/cli

Put a reeve bin on your PATH, or run bunx reeve. Application package.json scripts call it before Next:

{
  "scripts": {
    "dev": "reeve route:sync && bun run --bun next dev",
    "build": "reeve route:sync && bun run --bun next build",
    "check": "reeve doctor"
  }
}

Basic Usage

reeve make:model Post -mfcpw
reeve route:sync
reeve bailiff --explain no-orphan-query
reeve doctor

Every TUI path prints the equivalent non-interactive command before running it. The header always shows app name, database driver, adapter, and environment.

Generators

reeve make:model Post -mfcpw
reeve make:controller PostController --resource
reeve make:request StorePostRequest
reeve make:policy PostPolicy --model=Post
reeve make:ward PostWard --model=Post
reeve make:event PostPublished
reeve make:listener NotifySubscribers --event=PostPublished --queued
reeve make:errand GenerateThumbnail
reeve make:action PublishPost
reeve make:middleware EnsureSubscribed
reeve make:command PruneDrafts
reeve make:view posts/Index
reeve make:auth
reeve make:driver storage r2
reeve make:package billing
reeve make:migration create_posts_table
reeve stub:publish

stub:publish ejects templates into stubs/ so you change generated shape without forking the framework.

reeve make:driver storage r2 scaffolds a package with every capability false, methods that throw unimplemented, a wired conformance suite, and a README that already passes docs:check. The certification path is docs/15-driver-authoring.md.

Database, wards, routes, errands

reeve migrate
reeve migrate:rollback
reeve migrate:fresh --seed
reeve migrate:status
reeve schema:pull
reeve db:seed
reeve ward:list
reeve ward:sync
reeve ward:check
reeve ward:explain Post read
reeve route:list
reeve route:sync
reeve errand:work
reeve errand:failed
reeve errand:retry all
reeve errand:flush

migrate:fresh names what it will destroy and requires typing the environment name when it is not local.

Doctor and inspect

reeve doctor
reeve bailiff
reeve bailiff --fix
reeve capabilities
reeve config:show
reeve about
reeve tinker --execute '1 + 1'

doctor aggregates Bailiff, ward coverage, environment, and the capability matrix into one exit code. docs:check lints every package README: required sections, TypeScript code blocks that parse, and every public export in the Method Reference table.

reeve docs:check
reeve docs:check packages/cli
reeve docs:check --workspace

Waive a section or export with an HTML comment in the README:

<!-- docs:check-waiver: section Features -->
<!-- docs:check-waiver: export internalHelper -->

Method Reference

Method / export	Signature	Description
`runReeve`	`(argv, io?) => Promise<number>`	CLI entry. Opens the TUI or runs a subcommand.
`runCommand`	`(command, argv, io) => Promise<number>`	Dispatches one parsed command.
`shouldUseTui`	`(argv, io) => boolean`	True for bare TTY invocations without `--no-tui`.
`processIO`	`() => ReeveIO`	Process cwd, stdout, TTY, and env.
`MENU`	`readonly MenuItem[]`	TUI catalog. Every row has a scriptable `command`.
`COMMANDS`	`string[]`	Unique command names.
`ReeveIO`	`interface`	Testable IO: `cwd`, `stdout`, `isTTY`, `env`, optional `confirm`.
`renderTui`	`(io) => Promise<void>`	Ink TUI. Prints `reeve <command>` before running a selection.
`makeModel`	`(io, name, options) => Promise<void>`	Writes a model and optional `-mfcpw` siblings.
`makeMigration`	`(io, name) => Promise<void>`	Writes a timestamped driver-owned migration module.
`publishStubs`	`(io) => Promise<readonly string[]>`	Ejects built-in templates into `stubs/`.
`writeFromStub`	`(io, stub, relative, name, extra?) => Promise<string>`	Renders a stub onto disk.
`studly`	`(name) => string`	PascalCase helper for generator names.
`snake`	`(name) => string`	snake_case helper.
`headerBits`	`(io) => { app, database, adapter, environment }`	TUI header fields.
`checkPackageDocs`	`(root: string) => Promise<DocsCheckResult>`	Lints one package README against house style.
`runDocsCheck`	`(argv, io) => Promise<number>`	CLI handler for `docs:check`, including `--workspace`.
`DocsCheckResult`	`interface`	`root`, `ok`, and `findings` from one package lint.
`DocsFinding`	`interface`	One missing section, unparsed block, or missing export.
`makeDriver`	`(io, contract, slug) => Promise<void>`	Scaffolds a driver package with conformance wired.
`DRIVER_CONTRACTS`	`string[]`	Contract names `make:driver` accepts.
`DriverContractSpec`	`interface`	Suite, types, capabilities, and method stubs for one contract.

Testing

Call runReeve with isTTY: false and a captured stdout. Generators write into a temp cwd.

import { runReeve } from '@avelon/cli'

const code = await runReeve(['make:model', 'Post'], {
  cwd: tempDir,
  stdout: { write: () => true },
  isTTY: false,
  env: { AVELON_ENV: 'local' },
})

bun test
bun run typecheck