CLI

Usage
  $ alinea <command> [options]

Available Commands
  init     Initialize a new Alinea project in the current directory
  dev      Start a development dashboard
  build    Generate types and content cache

For more info, run any command with the `--help` flag
  $ alinea init --help
  $ alinea dev --help

Options
  -v, --version    Displays current version
  -h, --help       Displays this message

The CLI requires Node.js 24 or higher (or Bun), and React 19 in the project. It loads environment variables from .env.local, or from .env when there is no .env.local, looking in the project directory and then its parents. Variables already set in the environment take precedence.

Commands

alinea init

Sets up Alinea in the current directory. Run once during setup, see the Quickstart. It fails when a config file already exists.

• Creates cms.ts (in src/ when the project has a src directory) with an example schema and workspace. Its production baseUrl is read from NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL, which Vercel sets, and falls back to http://localhost:3000.

• Creates a first entry in content/pages/welcome.json and a content/media folder.

• Prefixes the dev and build scripts in package.json with alinea dev -- and alinea build --. Scripts that already run alinea are left alone, and the formatting of package.json is kept.

• In a Next.js project (next in dependencies), creates the API route app/(alinea)/api/cms/route.ts and reminds you to wrap your Next.js config with withAlinea.

• Adds /public/admin.html and /public/admin/, where alinea build writes the dashboard, to .gitignore.

• Detects your package manager from the lockfile (bun.lock or bun.lockb, pnpm-lock.yaml, yarn.lock or package-lock.json, falling back to npm) and prints the command that starts the dashboard, such as bun alinea dev or npx alinea dev.

alinea dev

Starts the local dashboard, by default on http://localhost:4500, moving to the next free port when that one is taken. It watches your config and content: changes to cms.ts are recompiled and the dashboard reloads. It also serves the MCP server for coding agents at /mcp on the same port.

There is no login during development: you are signed in as the name and email of your git config, and edits are written straight to the JSON files in your content folder, ready to review and commit.

Pass another command after -- to run it alongside the dashboard. It is started once the config is compiled and receives the environment variables withAlinea needs to serve the dashboard on your site's adminPath:

# Start the dashboard and the Next.js development server
alinea dev -- next dev

Aliases
  $ alinea serve

Options
  -c, --config    Config file location
  -d, --dir       Root directory of the project
  -p, --port      Port to listen on
  --production    Use production backend
  --dev           Watch alinea sources

• --config: the config file, relative to the project directory. Without it Alinea looks for cms.ts, cms.tsx, cms.js or cms.jsx in the project directory and its src folder.

• --dir: the project directory, defaults to the current directory.

• --port: the port of the local dashboard and MCP server, defaults to 4500.

• --production: runs the local dashboard with NODE_ENV=production.

• --dev is only used when working on Alinea itself.

alinea build

Indexes your content into the @alinea/generated package your site reads its content from, and writes the dashboard to your public folder: public/admin.html and a public/admin/ asset folder for the default adminPath. alinea init adds both to .gitignore. Pass your own build command after -- and it runs once the content is generated; alinea build exits with that command's exit code, so a failing next build fails your CI.

# Generate content, then build the Next.js site
alinea build -- next build

Aliases
  $ alinea generate

Options
  -c, --config    Config file location
  -d, --dir       Root directory of the project
  --fix           Any missing or incorrect properties will be overwritten by their default

--config and --dir work as for alinea dev. --fix rewrites content files whose data doesn't match the schema, filling missing or invalid properties with their defaults, and exits without running the command after --. Commit the result.

The build stops with an error when the config can't be loaded, when handlerUrl is missing or when baseUrl has no production URL, see Configuration.

Deploying

Make sure your hosting platform runs the build script from package.json, not next build directly. withAlinea gets the adminPath and handlerUrl from the CLI; when Next.js runs without it, it logs Alinea dashboard settings were not provided; dashboard routing is disabled and neither the dashboard nor media URLs are served. The same goes for development: run alinea dev -- next dev, not next dev on its own. See Deploy for setting up a backend.