CLI

Use the Farm CLI to run, build, generate types, migrate apps, deploy output, and add integrations.

Common commands

Upgrade Farm packages

farm upgrade --latestfarm upgrade --betafarm upgrade --latest --dry-run

--latest selects the newest stable release published under npm's latest tag. --beta selects the newest prerelease published under the beta tag. Exactly one release channel is required.

Farm reads the app's dependencies and upgrades every published @farm.js/* package together. It detects npm, pnpm, Yarn, or Bun from packageManager and lockfiles, preserves whether each package is a regular, development, optional, or peer dependency, and skips local workspace:, file:, link:, portal:, and catalog: references. Use --dry-run to inspect the commands without changing the project.

Provider names

The integration generator supports ai, stripe, supabase, workos, auth0, clerk, better-auth, authjs, autumn, polar, resend, jobs-trigger, jobs-inngest, and unkey.

Add integrations

farm add integration stripefarm add integration stripe --uifarm add integration better-auth --uifarm add integration jobs-trigger

Without --ui, the CLI installs integration wiring. With --ui, it also installs app-owned shadcn-style components for the selected provider.

Generate types

farm generatefarm generate --check

farm dev refreshes generated route/API types automatically when page and API route files change. Use farm generate when you want to refresh the same files outside the dev server, such as in CI, before publishing a package, or after moving files while the dev server was stopped.

When integration database schemas are configured, farm generate also writes schema artifacts if Farm can detect the data layer. Pass --orm and --output when you want explicit schema output for a migration step.

farm generate --check computes the route, API, environment, and i18n declarations without writing to disk. It exits non-zero and lists every missing, stale, or obsolete generated file. Use it after a normal generation step when generated types are committed:

- run: farm generate --check

Schema output flags such as --orm and --output cannot be combined with --check; database schema generation can depend on migrations and remains an explicit write operation.

Framework migrations

farm migrate inspectfarm migrate nextfarm migrate next --writefarm migrate tanstack --write

Framework migrations are deterministic codemods. They inspect the project, print a dry-run plan by default, and only write when --write is passed. Existing target files are skipped unless --force is passed.

The Next.js migrator copies app or src/app into Farm's src/app, creates farm.config.ts, creates a minimal root layout when needed, rewrites supported imports from next/link, next/navigation, and next/headers, and updates package scripts to farm dev, farm build, and node .output/server/index.mjs.

The TanStack migrator converts file routes from src/routes or routes into src/app/**/page.tsx, maps $id to [id], maps $ to [...splat], and adds a default export for simple component: ComponentName route files.

Both migrators leave source files in place and print manual review notes for framework-specific APIs.

Run command migrations

farm migratefarm migrate --dry-runfarm migrate --command "pnpm prisma migrate deploy"

farm migrate runs one-shot commands from migrations.commands in farm.config.ts. Use it for app-owned database migrations, integration tables, provider setup commands, and CI steps that should happen before farm build.

import { defineConfig } from "@farm.js/core";export default defineConfig({  migrations: {    commands: [      {        name: "prisma",        command: "pnpm prisma migrate deploy",      },      {        name: "integration schema",        command: "farm generate --orm postgres --output ./schema/farm.sql",      },    ],  },});

Commands run sequentially and stop on the first failure. --dry-run prints the commands without executing them.

Instant preview

farm previewfarm preview --port 3000farm preview --name stripe-webhookfarm preview --url http://localhost:4319farm preview --dry-run

farm preview exposes the app that is already running locally. It does not build or deploy the app. Use it when a teammate, webhook provider, OAuth provider, mobile device, or browser automation tool needs a public URL for the current farm dev session.

Farm detects the running app on common local ports, or you can pass --port / --url when the app is running somewhere specific. By default @farm.js/tunnel tries to open one outbound WebSocket to the hosted Farm Preview relay and returns a URL such as https://stripe-webhook.preview.farming-labs.dev. During the relay rollout, the CLI falls back to compatibility gateway polling if the native connection is unavailable.

The preview terminal logs forwarded traffic:

GET /api/hello?name=something -> 200 621msPOST /api/auth/login -> 200 580ms

The local farm dev terminal logs the matched page, API route, and middleware work. Client components hydrate through the same public URL; early button clicks are queued and replayed after hydration so slow dev-mode module loading does not lose the click.

See Instant Preview for webhook setup, custom gateway configuration, troubleshooting, and security notes.

Diagnose the app

farm doctorfarm doctor --port 4319farm doctor --url http://localhost:4319farm doctor --offlinefarm doctor --fixfarm doctor --json

farm doctor first probes the running app at http://localhost:3000. A live app provides the most accurate result because Farm can report its resolved routes, API methods, middleware, integrations, storage mounts, schedules, workflows, layers, and deployment runtime. When no app is running, the command falls back to config and filesystem checks.

Pass --port or --url when the app runs somewhere else. An explicitly requested runtime that cannot be reached is reported as a warning before the project checks. Use --offline to skip the network probe entirely.

The command exits with a non-zero status only when a check fails. Warnings keep a zero exit status, so CI can distinguish broken configuration from production-readiness advice. --json prints the complete report without terminal formatting.

farm doctor --fix applies only corrections Farm can make without replacing application code. Today that means creating a missing src/app/layout.tsx; an existing file is never overwritten. The command reruns diagnostics after each correction and reports exactly which files it created.

See DevTools and Doctor for the browser dashboard, diagnostics, JSON contract, and CI examples.

Explain a route

farm explain /products/42farm explain /products/42 --json

farm explain resolves a URL against the app router without starting the app. It reports:

• the matching page file, route pattern, parameters, and source layer;
• inherited layouts and file- or config-based middleware;
• route-rule and module runtime controls, rendering mode, PPR, and cache settings;
• static or generated metadata and the nearest Open Graph and Twitter images;
• the deployment target, preset, runtime compatibility, and actionable warnings.

Use the text output while debugging and --json for tooling. The command is read-only and fails when no page route matches the supplied URL.

Build

farm build

farm build respects deploy.target, output, and provider-specific output options from farm.config.ts.

Plan a deployment

farm deploy --planfarm deploy --vercel --prod --plan

farm deploy --plan resolves the target, Nitro preset, runtime, output directory, and exact build and provider commands. It does not build, inspect build output, check credentials, or call a deployment CLI. This makes it safe to use during review and in CI policy checks.

Cron commands

farm cron listfarm cron list --jsonfarm cron run dailyCleanupfarm cron run dailyCleanup --url http://localhost:4319farm dev --cron

farm cron run reads the named schedule from farm.config.ts, sends GET to its configured route, and forwards CRON_SECRET as bearer authorization. farm dev --cron runs the same routes on their UTC schedules in memory, prevents overlap inside the local process, and stops with the dev server.

See Cron for configuration, production adapters, security, and reliability semantics.

Production notes

• Run farm generate in CI if generated route/API types are not committed.
• Run farm migrate before farm build when schema changes are deployed separately from app code.
• Use farm build before deployment to catch docs, API, route, and integration wiring issues.
• Prefer farm add integration <name> --ui only when you want generated UI files.
• Review generated integration files before committing them.