Ferrite apps with the Ferrite CLI

The Ferrite CLI is the primary development surface for Ferrite applications. It owns the complete local-file workflow: scaffolding, package composition, admission checks, tests, live development, source deployment, and operations.

Get started

ferrite new webapp storefront --with-tests
cd storefront
ferrite check
ferrite dev

Use webapp for content, API, SSE, and live reload. Use hello for a smaller request/reply API.

Develop locally

ferrite dev starts real Store, Queue, Stream, Transaction, and Object Storage semantics on your machine. It searches a bounded range if the requested port is busy, prints both loopback and LAN URLs, and keeps state across application restarts.

ferrite dev --port 8787
ferrite dev --instances 3
ferrite dev --chaos 5
ferrite dev --json

• --instances runs competing consumers against one plane set so you can see how horizontal scale behaves.
• --chaos kills the app periodically so lease redelivery and idempotency bugs become visible.
• --json emits one lifecycle object per line for agents and automation.
• --fresh discards local plane state; omit it for the normal durable loop.

Outbound HTTP is denied locally by default. --egress allow permits only the destinations already declared by the app.

Add packages

ferrite add agent-ready
ferrite add ferrite-auth
ferrite add mcp

Ferrite vendors source packages into the app’s src/ tree because deployable apps may depend on ferrite-app alone. Package manifests and provenance headers make the composition reproducible. Edit the package source, not a file marked @generated by ferrite-pkg.

Preview and deploy

ferrite preview                # ungated, isolated, auto-expiring URL
ferrite deploy                 # admitted source build and deployed host

A URL is success evidence, not progress decoration. The CLI prints it only after Ferrite reports a deployed build and the app answers a probe. If the local process exits after submission, inspect the deployment in the Dashboard before retrying.

Operate an app

ferrite account
ferrite status storefront
ferrite logs storefront
ferrite rcs status
ferrite rcs log

Use the Dashboard or Ferrite MCP for app inventory, scaling, domains, secrets, usage, releases, environments, notifications, rollback, and withdrawal. Those operations are not disguised as local CLI commands.

Use the CLI from an agent

Install the Agent Plugin so an agent knows when to use the CLI and when to use MCP. Prefer the CLI for any task involving source files, compilation, a long-running dev loop, or deploy progress. Use MCP for compact remote reads and focused control-plane actions.

For MCP-only clients, ferrite mcp-serve exposes the local workflow over stdio. The portable plugin configures the stateless HTTP MCP service for remote work.

Troubleshooting

• If compilation fails, fix the diagnostics above build_failed; Ferrite does not claim the previous process restarted.
• If content sync fails, fix the declared directory; the browser is not told a refresh succeeded.
• If authentication is missing, run ferrite login --ephemeral or configure an issued token.
• If a reply times out, publish it with ctx.reply_to_queue(&request.reply_to) rather than a hard-coded queue.

See CLI Commands for the complete command surface.