ddd CLI - ddd_cqrs

The ddd CLI is the fastest way to start a ddd_cqrs_es application and keep generated projects consistent as they grow. It is published by the ddd-cqrs-es-cli crate, installs a binary named ddd, and is released with the same version as ddd_cqrs_es. Use it for:

new app scaffolding with opinionated presets
fine-grained additions like events, commands, routes, projections, and tests
capability wiring for Redis, gRPC, tracing, snapshots, and idempotency
Spin runtime command resolution
agent/MCP workflows that need deterministic dry-run JSON before writing files

Install

Install the published CLI:

cargo install ddd-cqrs-es-cli --locked

Check that it is available:

ddd --help
ddd capabilities --json

When developing this repository locally, use the workspace binary instead:

cargo run -p ddd-cqrs-es-cli -- <args>

For example:

cargo run -p ddd-cqrs-es-cli -- init billing --preset basic --domain Invoice

Quick Start

Create a small domain-only project:

ddd init billing --preset basic --domain Invoice
cd billing
ddd check

Add a domain event:

ddd add event Invoice InvoicePaid --field amount:i64 --field paid_at:String

Add a command:

ddd add command Invoice PayInvoice --field amount:i64

Preview any write before applying it:

ddd --dry-run --format json add event Invoice PaymentFailed --field reason:String

The dry-run output reports the planned file operations without changing files.

Command Model

Every command supports the same global controls:

Option	Purpose
`--cwd <path>`	Run against a generated project without changing the shell directory.
`--dry-run`	Preview file operations or runtime command resolution without writing or executing.
`--format text\|json`	Choose human text or machine-readable JSON output.
`--force`	Allow overwriting files that would otherwise be protected. Inspect collisions first.
`--yes`	Reserved for non-interactive confirmations as workflows grow.

The main command groups are:

Command	Use
`ddd init <path>`	Create a generated project and `ddd.toml` manifest.
`ddd add ...`	Add aggregates, events, commands, routes, tests, projections, and related stubs.
`ddd enable ...`	Wire capabilities into an existing generated project.
`ddd serve`	Resolve and run the app through the selected Spin runtime command.
`ddd watch`	Resolve a rebuild/restart loop for the selected runtime command.
`ddd fresh`	Reset schema/data only. This does not start the server.
`ddd doctor`	Inspect required local tools.
`ddd check`	Validate the generated project manifest and required files.
`ddd matrix`	Print supported backend/realtime/transport combinations.
`ddd capabilities --json`	Expose the machine-readable CLI contract for agents and MCP tools.

Presets

Choose a preset with ddd init --preset <preset>.

Preset	Best For	Default Shape
`basic`	Learning the framework or building a pure domain crate.	Aggregate, command, event, fixture test, and in-memory example.
`leptos-wasi`	Full-stack app scaffolding for Leptos WASI on Spin.	Domain/application/store/server boundaries with REST/SSE and optional gRPC.
`native-api`	Native Rust API service shape.	Axum-style API scaffold with native SQL adapter features.
`worker`	Projection or process-manager workers.	Worker entrypoint plus projection/process-manager-oriented stubs.
`custom`	A minimal base for explicit, agent-chosen capabilities.	Starts from the basic shape and lets you add capabilities intentionally.

Examples:

ddd init billing --preset basic --domain Invoice
ddd init counter-app --preset leptos-wasi --domain Counter --db sqlite --runtime spin --transport http --ui leptos
ddd init counter-grpc --preset leptos-wasi --domain Counter --db postgres --runtime spin --transport both --ui leptos
ddd init projector --preset worker --domain Invoice --db mysql --realtime polling

Current CLI-generated apps are Spin-focused. The runtime value is spin.

Generated Manifest

Every generated project includes ddd.toml. The CLI uses this file to know what it can safely patch later. Example shape:

[project]
name = "billing"
preset = "basic"
runtime = "spin"
db = "sqlite"
realtime = "off"
transport = "http"
ui = "none"

[capabilities]
enabled = []

[domains.invoice]
aggregate = "Invoice"
module = "invoice"
commands = ["CreateInvoice"]
events = ["InvoiceCreated"]

If a project does not have ddd.toml, treat it as outside the supported generated-project patching path unless you intentionally adopt it.

Add Domain Code

Run ddd add ... from the generated project root, or pass --cwd <project>. Add a second aggregate:

ddd add aggregate BillingAccount

Add an event to an existing aggregate:

ddd add event Invoice InvoicePaid --field amount:i64 --field paid_at:String --event-type invoice_paid

Add a command:

ddd add command Invoice PayInvoice --field amount:i64

Field syntax is name:RustType. The CLI inserts generated variants into marker regions in the generated domain module and updates ddd.toml. Available add targets:

aggregate
event
command
error
projection
query
process-manager
snapshot
upcaster
route
grpc-method
server-fn
rest-endpoint
test

Common examples:

ddd add projection InvoiceLedger
ddd add query InvoiceSummary
ddd add process-manager PaymentSaga
ddd add snapshot InvoiceSnapshot
ddd add upcaster InvoicePaid --from 1 --to 2
ddd add route invoice-summary --method GET --path /api/invoices/summary
ddd add rest-endpoint invoice-payments --method POST --path /api/invoices/payments
ddd add server-fn pay-invoice
ddd add grpc-method pay-invoice
ddd add test invoice-payment

Enable Capabilities

Use ddd enable ... when the project exists and you want to wire a capability into ddd.toml and, where applicable, Cargo.toml feature flags.

ddd enable db postgres
ddd enable db mysql
ddd enable redis-store
ddd enable realtime redis
ddd enable grpc
ddd enable rest
ddd enable leptos
ddd enable idempotency
ddd enable snapshots
ddd enable tracing

Use dry-run JSON before enabling a capability in automation:

ddd --dry-run --format json enable realtime redis

Runtime Matrix

The CLI currently scaffolds Spin-focused apps. Supported values:

Axis	Values
Runtime	`spin`
DB	`sqlite`, `postgres`, `neon`, `supabase`, `turso`, `mysql`, `redis`
Realtime	`off`, `polling`, `redis`
Transport	`http`, `grpc`, `both`
UI	`none`, `leptos`

Use the CLI to inspect the live matrix:

ddd matrix
ddd capabilities --json

Redis has two separate meanings:

db=redis means Redis is the durable event/checkpoint/read-model store.
realtime=redis means Redis is only the wake/notification transport unless db=redis is also selected.

Spin supports transport=http, transport=grpc, and transport=both.

Serve, Watch, and Fresh

The runtime commands read from ddd.toml and can be overridden with flags. Preview the command:

ddd --dry-run --format json serve

Serve the app:

ddd serve
ddd serve --db postgres --realtime redis --transport http

Watch and restart:

ddd watch

Reset data only:

ddd fresh --db sqlite

fresh is reset-only. It should not start the server.

Agent and MCP Workflow

Agents should use JSON dry-runs before changing files:

ddd --cwd billing --dry-run --format json add event Invoice InvoicePaid --field amount:i64

The report includes:

{
  "status": "planned",
  "message": "project extension complete",
  "operations": [
    {
      "action": "update",
      "path": "src/domain/invoice.rs",
      "bytes": 2048,
      "description": "add domain event"
    }
  ]
}

A safe agent loop is:

Run ddd capabilities --json.
Run ddd matrix if runtime/backend choices matter.
Run the mutating command with --dry-run --format json.
Inspect operations.
Apply the same command without --dry-run.
Run ddd check.
Run project tests.

File and Symbol Targeting

The current CLI targets generated projects through ddd.toml, aggregate names, and marker regions. This syntax is not currently implemented:

/path/to/file.rs:Struct
/path/to/file.rs:EnumVariant
/path/to/file.rs:function_name

If you need path or symbol targeting, add explicit CLI support and tests first, or patch the file manually with Rust-aware edits. Do not pass unsupported selector syntax to ddd.

Release Pairing

The library and CLI are versioned together. For maintainers:

make version 0.2.5
make publish dry-run

Reliable publish dry-run forms are:

make publish dry-run
make publish -- --dry-run

Real publish:

make publish

Run cargo login first, or provide CARGO_REGISTRY_TOKEN in the environment. The release script validates that ddd_cqrs_es and ddd-cqrs-es-cli have matching versions, then publishes ddd_cqrs_es before ddd-cqrs-es-cli.

Troubleshooting

ddd check fails with missing generated files:

Run it from the generated project root or pass --cwd <project>.
Confirm ddd.toml, Cargo.toml, and src/domain/mod.rs exist.

ddd add event cannot find an aggregate:

Use the aggregate name from ddd.toml.
Run ddd add aggregate <Name> first if the aggregate does not exist.

--runtime wasmtime is rejected:

The CLI-generated runtime is currently Spin-only.
Use spin, or check ddd capabilities --json after upgrading the CLI.

A file already exists:

Inspect the file before using --force.
Prefer dry-run JSON to see exactly which path is colliding.

​Install

​Quick Start

​Command Model

​Presets

​Generated Manifest

​Add Domain Code

​Enable Capabilities

​Runtime Matrix

​Serve, Watch, and Fresh

​Agent and MCP Workflow

​File and Symbol Targeting

​Release Pairing

​Troubleshooting