# Ferrite apps with the Ferrite CLI

Use the Ferrite CLI to create, develop, test, preview, deploy, and operate an app from one local workflow.

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

```bash
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.

```bash
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

```bash
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

```bash
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

```bash
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](/developers/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](/developers/cli-commands/) for the complete command surface.