CLI
Every command @cairn-cms/cli actually has, generated from its own dispatch table.
cairn init
Set up Cairn in an existing project - or a brand-new one, if run in an empty directory: logs you in, connects (or creates) a project, starts the schema files, scaffolds the client and optional live-preview routes, and wires schema syncing into your dev server.
cairn init [flags]Flags
--project | CAIRN_PROJECT_ID | Project slug - defaults to NEXT_PUBLIC_CAIRN_PROJECT_ID / VITE_CAIRN_PROJECT_ID / CAIRN_PROJECT_ID from the environment or .env.local/.env |
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
--dir | CAIRN_SCHEMA_DIR | Schema files directory (defaults to cairn/schema) |
cairn login
Log in from the terminal: shows a one-time code and opens the Dashboard to approve it. The session is stored in ~/.config/cairn and works for every project you're a member of.
cairn login [flags]Flags
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
--no-browser | Print the approval link instead of opening it |
cairn logout
Revoke and forget the stored `cairn login` session.
cairn logout [flags]Flags
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
cairn whoami
Show who the CLI is acting as, and the projects that account can reach.
cairn whoami [flags]Flags
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
--json | Machine-readable output |
cairn schema pull
Write the project's deployed schema to schema files (cairn/schema) - how an existing project moves its schema into code.
cairn schema pull [flags]Flags
--project | CAIRN_PROJECT_ID | Project slug - defaults to NEXT_PUBLIC_CAIRN_PROJECT_ID / VITE_CAIRN_PROJECT_ID / CAIRN_PROJECT_ID from the environment or .env.local/.env |
--token | CAIRN_TOKEN | A project token (Dashboard -> Settings -> API tokens) instead of your `cairn login` session - what CI uses. Never prefix it with NEXT_PUBLIC_/VITE_ |
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
--dir | CAIRN_SCHEMA_DIR | Schema files directory (defaults to cairn/schema) |
--force | Replace schema files that already exist | |
--json | Print one JSON object (`ok`, `status`, and any `changes`/`impact`/`errors`/`warnings`) instead of text - for scripts and AI agents. The exit code still reports failure |
cairn schema diff
Show what deploying the schema files would change, and how much stored content each change affects. Changes nothing.
cairn schema diff [flags]Flags
--project | CAIRN_PROJECT_ID | Project slug - defaults to NEXT_PUBLIC_CAIRN_PROJECT_ID / VITE_CAIRN_PROJECT_ID / CAIRN_PROJECT_ID from the environment or .env.local/.env |
--token | CAIRN_TOKEN | A project token (Dashboard -> Settings -> API tokens) instead of your `cairn login` session - what CI uses. Never prefix it with NEXT_PUBLIC_/VITE_ |
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
--dir | CAIRN_SCHEMA_DIR | Schema files directory (defaults to cairn/schema) |
--json | Print one JSON object (`ok`, `status`, and any `changes`/`impact`/`errors`/`warnings`) instead of text - for scripts and AI agents. The exit code still reports failure |
cairn schema deploy
Deploy the schema files to the project, migrating existing documents (renames via `renamedFrom`, type conversions). Refuses any change that would delete stored content unless --allow-data-loss is passed.
cairn schema deploy [flags]Flags
--project | CAIRN_PROJECT_ID | Project slug - defaults to NEXT_PUBLIC_CAIRN_PROJECT_ID / VITE_CAIRN_PROJECT_ID / CAIRN_PROJECT_ID from the environment or .env.local/.env |
--token | CAIRN_TOKEN | A project token (Dashboard -> Settings -> API tokens) instead of your `cairn login` session - what CI uses. Never prefix it with NEXT_PUBLIC_/VITE_ |
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
--dir | CAIRN_SCHEMA_DIR | Schema files directory (defaults to cairn/schema) |
--allow-data-loss | Deploy even if fields' values would be deleted or documents orphaned | |
--dry-run | Same as `cairn schema diff` | |
--json | Print one JSON object (`ok`, `status`, and any `changes`/`impact`/`errors`/`warnings`) instead of text - for scripts and AI agents. The exit code still reports failure |
cairn schema validate
Check the schema files - locally, and against the server's full validation (as a dry run) when a project and login are configured.
cairn schema validate [flags]Flags
--project | CAIRN_PROJECT_ID | Project slug - defaults to NEXT_PUBLIC_CAIRN_PROJECT_ID / VITE_CAIRN_PROJECT_ID / CAIRN_PROJECT_ID from the environment or .env.local/.env |
--token | CAIRN_TOKEN | A project token (Dashboard -> Settings -> API tokens) instead of your `cairn login` session - what CI uses. Never prefix it with NEXT_PUBLIC_/VITE_ |
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
--dir | CAIRN_SCHEMA_DIR | Schema files directory (defaults to cairn/schema) |
--json | Print one JSON object (`ok`, `status`, and any `changes`/`impact`/`errors`/`warnings`) instead of text - for scripts and AI agents. The exit code still reports failure |
cairn schema reference
Print the schema file format as Markdown: every document type key, field type and option, with an example. Matches this CLI's version - the same page is at https://cairn.press/schema/reference.md.
cairn schema referencecairn agents
Write (or refresh) the Cairn section of AGENTS.md - where the schema lives, the safe way to change and deploy it, and how to read content - so coding agents get it right. Creates a CLAUDE.md that imports AGENTS.md if there isn't one. `cairn init` does this too.
cairn agents [flags]Flags
--project | CAIRN_PROJECT_ID | Project slug - defaults to NEXT_PUBLIC_CAIRN_PROJECT_ID / VITE_CAIRN_PROJECT_ID / CAIRN_PROJECT_ID from the environment or .env.local/.env |
--dir | CAIRN_SCHEMA_DIR | Schema files directory (defaults to cairn/schema) |
cairn typegen
Generate TypeScript types from the schema files (or, with --remote, the deployed schema), so client.fetch<Post>('post') is fully typed.
cairn typegen [flags]Flags
--dir | CAIRN_SCHEMA_DIR | Schema files directory (defaults to cairn/schema) |
--out | Output path for the generated types file (defaults to cairn/types.ts) | |
--remote | Generate from the deployed schema instead of local files | |
--project | CAIRN_PROJECT_ID | Project slug - defaults to NEXT_PUBLIC_CAIRN_PROJECT_ID / VITE_CAIRN_PROJECT_ID / CAIRN_PROJECT_ID from the environment or .env.local/.env |
--token | CAIRN_TOKEN | A project token (Dashboard -> Settings -> API tokens) instead of your `cairn login` session - what CI uses. Never prefix it with NEXT_PUBLIC_/VITE_ |
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
cairn dev
Watch the schema files: regenerate types and deploy safe changes on every save. Changes that would delete content are reported, never deployed. (Next.js apps wrapped in withCairn get this inside `next dev`.)
cairn dev [flags]Flags
--project | CAIRN_PROJECT_ID | Project slug - defaults to NEXT_PUBLIC_CAIRN_PROJECT_ID / VITE_CAIRN_PROJECT_ID / CAIRN_PROJECT_ID from the environment or .env.local/.env |
--token | CAIRN_TOKEN | A project token (Dashboard -> Settings -> API tokens) instead of your `cairn login` session - what CI uses. Never prefix it with NEXT_PUBLIC_/VITE_ |
--api-url | CAIRN_API_URL | Override the API base URL (defaults to https://api.cairn.press) |
--dir | CAIRN_SCHEMA_DIR | Schema files directory (defaults to cairn/schema) |
--out | Output path for the generated types file (defaults to cairn/types.ts) | |
--no-deploy | Only regenerate types |