CLI

Use the CLI to run Rad, apply rad.schema.yaml, and generate a typed client from the accepted schema.

Commands

rad init

Create rad.config.yaml and rad.schema.yaml in a new or existing project directory. In a terminal, Rad guides you through the small set of project choices. Use --yes to accept defaults without prompts. Existing project files are never overwritten, and accepted rad.state is created only by a successful schema migration or pull.

Documentation: https://www.radengine.dev/docs/cli#rad-init

rad serve

Run Rad until interrupted. A write instance owns the Slate writer; any number of read instances can serve polling checkpoint views of the same storage path. A fresh database defaults to direct catalog management; pass --catalog-mode schema when rad.schema.yaml should own all catalog changes. Catalog mode is immutable after database initialization.

The public API uses --addr (default port 7237). The administration UI uses the following port (default 7238). Pass --frontend postgres to also expose the PostgreSQL wire protocol on port 5432.

Documentation: https://www.radengine.dev/docs/cli#rad-serve

rad validate

Parse and validate rad.schema.yaml structure, types, identities, constraints, indexes, and references without changing any state or contacting the configured database.

Documentation: https://www.radengine.dev/docs/schemas

rad doctor

Run read-only checks against rad.config.yaml, rad.schema.yaml, rad.state, the configured server, generated clients, and durable schema transitions. Warnings identify expected or recoverable drift. Failed checks make the command exit unsuccessfully.

Documentation: https://www.radengine.dev/docs/cli#rad-doctor

rad schema

Manage the desired schema in rad.schema.yaml, the database's accepted schema, local accepted state in rad.state, generated clients, and durable online transition work.

Safe workflow: rad validate rad schema diff rad schema migrate rad schema status

Documentation: https://www.radengine.dev/docs/schemas/manage

rad schema status

Read the server schema, local immutable accepted snapshot, and desired schema, verify configured generated clients, then summarize whether all four copies are synchronized. This command does not modify the project or database.

Documentation: https://www.radengine.dev/docs/schemas/manage#1-check-the-four-copies

rad schema diff

Ask the server to plan rad.schema.yaml against the current accepted schema. The plan is read-only and point-in-time. Migration replans transactionally before applying. Destructive findings require explicit consent; blocking findings cannot be bypassed.

Documentation: https://www.radengine.dev/docs/schemas/manage#2-review-the-plan

rad schema migrate

Replan and apply the desired schema against the current catalog. Rad refuses blocking changes, requests explicit consent for reported data loss, waits for durable online transitions, updates rad.state, and regenerates configured clients.

In non-interactive mode, a destructive plan fails unless --accept-data-loss is supplied. Never add that flag without reviewing the JSON diff and obtaining the user's consent.

Documentation: https://www.radengine.dev/docs/schemas/manage#3-apply-and-wait

rad schema pull

Use the server's accepted schema as the source of truth. Pull refuses to overwrite a locally modified rad.schema.yaml unless --force is supplied; forced pulls first write a timestamped backup.

Pull is a recovery operation, not the normal way to accept desired schema changes.

Documentation: https://www.radengine.dev/docs/schemas/manage#recover-local-state-from-the-server

rad schema json-schema

Emit the exact rad.schema.yaml JSON Schema bundled with this Rad binary. Use it for offline validation, editor integration, or agent introspection.

Documentation: https://www.radengine.dev/docs/schemas

rad schema transitions

Observe the authoritative lifecycle state of schema transitions. Progress counters are advisory; ready, failed, and cancelled are terminal states.

Documentation: https://www.radengine.dev/docs/schemas/monitor

rad schema transitions list

List active transitions and retained terminal records. Filter by protocol kind or lifecycle state without changing work.

Documentation: https://www.radengine.dev/docs/schemas/monitor

rad schema transitions get

Read the durable control record, progress counters, retained-work pressure, and last error for one transition.

Documentation: https://www.radengine.dev/docs/schemas/transitions

rad schema transitions wait

Poll one transition until it becomes ready, failed, or cancelled. The wait has explicit interval and timeout bounds and never advances the transition itself.

Documentation: https://www.radengine.dev/docs/schemas/monitor

rad schema transitions cancel

Cancel only when abandoning the requested schema change. The operation is idempotent for an already-cancelled transition and rejects ready or failed terminal work. Use --yes for unattended execution.

Documentation: https://www.radengine.dev/docs/schemas/monitor

rad generate

Generate a typed client from the immutable accepted schema snapshot recorded by rad schema migrate or rad schema pull. Generation refuses to target unapplied desired changes. rad generate reads accepted state; it does not create or repair it.

Documentation: https://www.radengine.dev/docs/concepts/schemas-and-clients

rad skills

Rad ships one Agent Skills-compatible guide covering project setup, declarative schema editing, migration safety, client generation, diagnostics, and operations. The bundled instructions always match this binary.

Agent Skills standard: https://agentskills.io Documentation: https://www.radengine.dev/docs/cli#rad-skills

rad skills list

List the Agent Skills-compatible guides embedded in this Rad binary.

Documentation: https://www.radengine.dev/docs/cli#rad-skills-list

rad skills get

Print the canonical skill instructions matching this binary. Add --full to include each referenced guide in the same response.

Documentation: https://www.radengine.dev/docs/cli#rad-skills-get

rad skills path

Write the complete, version-matched skill into Rad's cache and print its root directory for agents that load skills from the filesystem. Set RAD_SKILLS_DIR to choose the parent directory.

Documentation: https://www.radengine.dev/docs/cli#rad-skills-path

rad spec

Emit the exact command contract used to generate this binary's parser and CLI documentation. YAML is the normative source; JSON is available for machine consumers.

Documentation: https://www.radengine.dev/docs/cli#rad-spec

Exit codes