Reference / Commands

Every command, in one place.

Frappé, your application’s binary, and Latte, listed from the source of Caramel 0.15.0.

Contract	Value
Release	0.15.0
Needs	An application folder, except commands marked as working anywhere
Covers	Frappé, your application’s binary, Latte
Proved by	`frappe COMMAND --help`

Learning it for the first time? Your first application runs the everyday commands in order. This page lists every command.

Limits at a glance

Limit	Value
Exit status	0 success, 1 failure, 2 usage error (application binary and Latte)
`frappe corretto --concurrency`	1–8
`frappe db branch create NAME`	a lowercase letter, then up to 30 lowercase letters, digits or underscores
`frappe traces --limit` default	20
`frappe logs` lines	200

Frappé runs the release your application pins

Condition	Outcome
A command marked “Works outside an application”	works anywhere
Every other command	runs inside an application folder
An application whose `shard.lock` pins a Caramel release	Frappé runs that release’s commands for it
`frappe COMMAND --help`	prints one command’s syntax
`frappe agent-manifest`	prints the whole list with the diagnostic grammar for agents

frappe helpPrint every command with its description. Works outside an application.

frappe versionPrint the Frappé version. Works outside an application.

frappe agent-manifestPrint the release's version and the addresses of its documentation and guides, this strict command list and the MRDP diagnostic grammar for coding agents. Works outside an application.

frappe new NAMECreate the application ./NAME, install its locked dependencies and register it with Latte. Works outside an application.

frappe setupInstall locked dependencies and register this project with Latte, preserving existing files.

frappe dev [--no-open] [--branch NAME]Build, serve and reload the app at its HTTPS origin; --branch runs it against database branch NAME.

frappe check [--agent|--human]Run the Tier-1 type check (crystal build --no-codegen) and report diagnostics; MRDP unless stdout is a TTY.

frappe lint [--agent|--human]Check the application against Caramel's rule set in .ameba.yml; MRDP unless stdout is a TTY.

frappe formatFormat the application's Crystal files with the pinned compiler's formatter.

frappe routes [FILTER]List routes with their contracts; FILTER keeps routes whose method, path or action contains it (any case).

frappe expand FILE:LINE:COLPrint the plain Crystal that the macro call at FILE:LINE:COL expands to; where none expands, the call whose block encloses it, such as `contract` for a `field`, and say which.

frappe make resource NAME FIELD:TYPE... [--plural=NAME] [--only=ACTIONS] [--central]Generate a SugarORM schema, migration, actions, views, routes and specs; FIELD:TYPE:server marks a field the server sets, kept out of forms and contracts, :unique adds a unique index and changeset constraint, and :url validates an http or https URL entered in a URL input. --only=create,show,index,new keeps the listed actions of index, show, new, create, edit, update and destroy; create and show are required, and edit needs new and update. In a multi-tenant application a resource belongs to the tenant unless --central is given.

frappe make locale CODEAdd the locale CODE, such as fr or pt-BR: create app/locales/CODE.cr; on first use also app/locales/en.cr and the i18n lines in config/application.cr, after which frappe make resource writes translated views.

frappe make tenancy MODELMake the application multi-tenant with MODEL, such as Account, as the tenant: its schema, migration, sign-up page at /PLURAL/new and home at /SLUG, require "caramel/tenancy" and the tenant block in config/routes.cr; frappe make resource then writes resources that belong to a tenant.

frappe make domain NAME CONTEXT --means=TEXT [--central]Start a SweetTalk domain: app/domain/NAME.cr with its first context CONTEXT, which means TEXT, and spec/domain/NAME_spec.cr; on first use also require "caramel/sweet_talk" and require "../app/domain/*" in config/application.cr. When the application has no SweetTalk skill for agents, it also writes .claude/skills/sweettalk/SKILL.md. In a multi-tenant application the domain names the tenant, and --central makes the context one every tenant shares.

frappe translationsList the keys each locale still takes from the default locale; exits 1 while any is missing.

frappe migrate [--dev-override] [--agent|--human]Lint and apply pending migrations, then report schema drift read-only.

frappe seedLoad db/seeds.cr into the development database.

frappe buildBuild the Linux release artifact in a container: a static linux/amd64 binary and public/ in .caramel/build/; refuses uncommitted changes and prints the artifact's path.

frappe corretto [SPEC_PATHS...] [--concurrency=1..8]Run specs in isolated Latte test databases with synchronous queue drains.

frappe db dumpSave a backup of the development database.

frappe db restore FILERestore the development database from FILE after a safety backup.

frappe db diff --name NAME [--dev-override] [--agent|--human]Derive migrations from the declared schema and prove them on a scratch branch.

frappe db branch create NAMEClone the development database into branch NAME and print its connection URL.

frappe db branch listList this project's database branches.

frappe db branch delete NAMEDrop database branch NAME.

frappe db diagnoseReport database health: connections, locks, cache hits, unused indexes and the slowest statements.

frappe logs [app|compiler|access] [--follow]Show the development app or compiler log, or Caddy's access log.

frappe traces [--errors] [--slow=MS] [--limit=N] [--agent|--human]List the development session's recent requests, jobs and schedule runs, newest first.

frappe trace REF [--md]Show one development trace: its summary, queries, logs and error. REF is last, last-error, or a prefix of a trace id, a request id or an error fingerprint.

frappe errors [--agent|--human]List development runtime errors and repeated queries, grouped.

frappe services [status|start|stop]Show, start or stop Latte's PostgreSQL, DNS and HTTPS services. Works outside an application.

frappe sitesList the sites registered with Latte. Works outside an application.

frappe sites remove NAMEUnregister site NAME, keeping its files, databases, credentials, logs and backups. Works outside an application.

frappe installations [list]List the Caramel releases installed on this Mac. Works outside an application.

frappe installations install VERSIONClone, build and register the tagged release VERSION, reusing this toolchain when the release pins the same one; if VERSION is installed, build what it lacks, such as its linter. Works outside an application.

frappe installations registerRegister this checkout for projects pinned to its version; ~/.local/bin/frappe and latte run the newest installed release. Works outside an application.

frappe installations remove VERSIONForget the installation registered for VERSION; the launchers move to the newest remaining release. Works outside an application.

frappe doctorCheck the toolchain, this Caramel installation, dependencies, local configuration, Latte services, trusted HTTPS and the port relay.

frappe openOpen the application's HTTPS origin in the browser.

frappe lsp crystalline|ameba-ls [SERVER_ARGS...]Run a pinned language server for this project on stdio.

frappe lsp installBuild the pinned language servers. Works outside an application.

Diagnostics follow where stdout goes

Condition	Outcome
`check`, `lint`, `migrate`, `db diff`, `traces` or `errors` when stdout is not a terminal	prints MRDP diagnostics
`--agent`	prints MRDP diagnostics
`--human`	prints the terminal layout
A mistyped command or option on a terminal	exits 1 with `frappe migrte: unknown command migrte`, the intended command’s `Usage:` line and `Did you mean migrate?`
A mistyped command or option when stdout is not a terminal, or with `--agent`	exits 1 with one MRDP `USAGE` block: `MSG`, `SYNTAX` and `SUGGEST`
`frappe corretto --concurrency` outside 1 to 8	refuses
`frappe db branch create NAME` that is not a lowercase letter followed by up to 30 lowercase letters, digits or underscores	exits 1 with `branch name NAME must be a lowercase letter followed by up to 30 lowercase letters, digits or underscores`
`frappe traces` without `--limit`	prints at most 20 traces
`frappe logs`	prints the last 200 lines

Read diagnostics as an agent →

The application binary takes its own commands

Each application compiles to one binary whose main is Caramel.run(App); below, APP stands for it. Frappé runs these commands for you: frappe dev serves, frappe routes, frappe seed, frappe migrate and frappe translations run the commands of the same name, frappe db diff runs schema, frappe db diagnose runs db diagnose and frappe corretto runs migrate on the spec database. frappe build compiles the same binary for Linux in a container, so it needs a container engine such as Docker Desktop. serve and work are the two process roles. ops, jobs, db diagnose and insights belong to Crema, which also lets your application add commands of its own.

Condition	Outcome
Any binary command	exits 0 on success, 1 on failure, 2 on a usage error
`serve` or `work` with pending migrations	stops with `Pending migrations. Run frappe migrate first.`

APP serve [--no-workers]Serve HTTP on the private socket CARAMEL_SOCKET names, with Cold Brew’s workers, maintenance and schedules; --no-workers keeps the PubSub broker and maintenance but runs no workers or schedules, for a deployment that runs work separately. CARAMEL_ROOT, when set, names the directory whose public/ it serves. Refuses to start with pending migrations.

APP work [--queues=NAMES] [--concurrency=N] [--no-scheduler]Run Cold Brew’s workers, maintenance and schedules without HTTP. --queues and --concurrency replace CARAMEL_WORKER_QUEUES and CARAMEL_WORKER_CONCURRENCY; --no-scheduler leaves schedules to other processes.

APP seedLoad db/seeds.cr into the database.

APP routesPrint every route with its action, contract and ingress.

APP schemaPrint the declared schema as JSON.

APP driftCompare the database with the declared schema; exits 1 when they differ.

APP translationsList the keys each locale still takes from the default locale; exits 1 while any is missing.

APP migrate [--dev-override]Lint and apply pending migrations; --dev-override relaxes the linter in development.

APP lint [--dev-override]Lint pending migrations without applying them; --dev-override relaxes the linter in development.

APP jobs [stats|failed|show ID|retry ID|--class=NAME|unknown]Count each queue’s jobs, list failures, show one job with its stored error, or retry failed jobs. Needs the database, not a running application. unknown prints queued job classes this binary does not compile, one per line, and exits 1 when any exist.

APP db diagnose|roles DATABASE MIGRATION_ROLE RUNTIME_ROLEdiagnose reports database health: connections, locks, cache hits, unused indexes and the slowest statements, and needs the database, not a running application. roles prints the psql script that creates an application’s migration and runtime roles and its database.

APP insights [--since=DURATION] [--kind=request|job|schedule|sql|outbound]Show the recorder’s per-minute latency history for routes, jobs, schedules, SQL or outbound hosts. Needs require "caramel/crema/recorder".

Frappé starts Latte when a command needs it

Frappé runs latte daemon --detach when a command needs the services and Latte is not running, and frappe services starts and stops the services Latte runs. You call Latte yourself for the login item, certificate trust and its version.

Condition	Outcome
An unknown Latte command	exits 2 with `Unknown command. Use latte --help.`
`latte version`	prints `Latte 0.16.0 (control API 1, 2)`

latte daemonRun Latte in this terminal.

latte daemon --detachRun Latte in its own session, logging to logs/latte.log. Frappé starts Latte this way when it is not running.

latte stopStop the running Latte. Services keep running.

latte service installStart Latte whenever you log in (a per-user login item), and now.

latte service uninstallRemove that login item; the Latte it started stops.

latte trust installTrust Latte's certificate authority in your default keychain.

latte trust removeRemove that one certificate from the keychain it was added to.

latte versionPrint this Latte's release and the control API versions it serves.

Prove it

Ask for the syntax

Terminal · inside the application

frappe check --help
frappe agent-manifest
frappe migrte

Passing: --help prints Usage: frappe check … and the command’s summary. agent-manifest prints every command with the diagnostic grammar. The mistyped migrte exits 1: on a terminal with frappe migrte: unknown command migrte, the Usage: line of migrate and Did you mean migrate?; piped, with one MRDP USAGE block.

← Security defaults Set up the local environment →