cli

contentrain

CLI for Contentrain.

Start here:

• 2-minute product demo
• CLI docs
• Getting started

contentrain is the local operations surface for a Contentrain project:

• initialize .contentrain/ in an existing repo
• inspect project health and validation state
• generate the typed #contentrain SDK client
• review pending cr/* branches
• run the local review UI
• expose the MCP server over stdio (IDE agents) or HTTP (Studio, CI, remote drivers)

This package is the human-facing companion to:

• @contentrain/mcp for deterministic content operations
• @contentrain/query for generated runtime queries
• @contentrain/rules and @contentrain/skills for agent guidance

Install

Use npx:

npx contentrain init

Or install globally:

pnpm add -g contentrain
contentrain status

Requirements:

• Node.js 22+
• Git available in PATH

Global Flags

Flag	Env var	Description
--debug	CONTENTRAIN_DEBUG=1	Verbose debug logging to stderr (works on every subcommand)

Example: contentrain --debug status or CONTENTRAIN_DEBUG=1 contentrain validate.

Commands

Command	Purpose
contentrain init	Initialize .contentrain/, git workflow, templates, and IDE rules
contentrain status	Show project overview, models, branch pressure, and validation summary
contentrain doctor	Check setup health, SDK freshness, orphan content, and branch limits
contentrain validate	Validate content against schemas, optionally create review-branch fixes
contentrain generate	Generate .contentrain/client/ and #contentrain package imports
contentrain diff	Review and merge or reject pending cr/* branches interactively
contentrain merge <branch>	Merge one pending cr/* branch non-interactively (CI/agents)
contentrain describe <model>	Inspect a model's schema, stats, and import snippet
contentrain describe-format	Print the Contentrain content-format specification
contentrain scaffold --template	Apply a template (blog, landing, docs, ecommerce, saas, i18n, mobile)
contentrain setup <agent|--all>	Configure MCP server + AI rules for IDE (Claude Code, Cursor, Windsurf, VSCode, Copilot)
contentrain skills	Install, update, or list Contentrain AI skills and IDE rules
contentrain serve	Start the local review UI (REST + WS), MCP stdio server (--stdio), or MCP HTTP server (--mcpHttp)
contentrain studio connect	Connect a repository to a Studio project
contentrain studio login	Authenticate with Contentrain Studio
contentrain studio logout	Log out from Studio
contentrain studio whoami	Show current authentication status
contentrain studio status	Show project overview from Studio
contentrain studio activity	Show recent activity feed
contentrain studio usage	Show workspace usage metrics
contentrain studio branches	Manage remote content branches
contentrain studio cdn-init	Set up CDN for content delivery
contentrain studio cdn-build	Trigger a CDN rebuild
contentrain studio webhooks	Manage webhooks
contentrain studio submissions	Manage form submissions

Flag Matrix

Every read command supports --json for CI use; write commands surface --watch or --yes where they apply:

Command	Notable flags
status	--json
doctor	--json, --usage — non-zero exit on failure
validate	--json, --fix, --interactive, --watch, --model <id>
generate	--json, --watch
diff	--json
merge	--yes (skip confirm)
describe	--sample, --locale, --json
scaffold	--template <id>, --locales <csv>, --no-sample, --json
serve	--port, --host, --open, --demo, --stdio, --mcpHttp, --authToken

Typical Flow

Initialize a project:

contentrain init

Check project state (with optional JSON for CI):

contentrain status
contentrain status --json

contentrain doctor
contentrain doctor --json
contentrain doctor --usage  # Analyze content key usage

Generate the typed SDK client:

contentrain generate
contentrain generate --watch    # Watch for changes
contentrain generate --json     # CI-friendly JSON output

Validate content and create review-branch fixes:

contentrain validate
contentrain validate --fix
contentrain validate --watch    # Live validation in dev mode
contentrain validate --json     # CI output

Review pending changes:

contentrain diff
contentrain diff --json  # CI integration

Open the local UI:

contentrain serve
contentrain serve --demo  # Start with a temporary demo project

Enable detailed logging:

contentrain --debug status
CONTENTRAIN_DEBUG=1 contentrain validate  # Via environment variable

serve Modes

contentrain serve has three roles.

Local review UI (default)

contentrain serve
contentrain serve --port 3333 --host localhost
contentrain serve --demo  # Temporary project (no setup needed)

Serves REST endpoints for status / content / validation / branches / normalize / doctor / describe-format / preview-merge, a WebSocket stream for live updates, and the embedded Vue serve-ui app bundled with the CLI.

WebSocket event types: connected, config:changed, context:changed, meta:changed, model:changed, content:changed, branch:created, branch:merged, branch:rejected, branch:merge-conflict, sync:warning, validation:updated, normalize:plan-updated, file-watch:error.

MCP stdio (IDE agents)

contentrain serve --stdio

Use stdio mode when connecting Claude Code, Cursor, Windsurf, or another MCP client to the local project.

MCP HTTP (Studio, CI, remote drivers)

contentrain serve --mcpHttp --authToken $(openssl rand -hex 32)
contentrain serve --mcpHttp --port 3333 --host 0.0.0.0 --authToken $TOKEN

Spins up a Streamable HTTP MCP server at POST /mcp. Bearer auth is required on non-localhost binds — the CLI hard-errors when no --authToken is set for an exposed interface (OWASP Secure-by-Default). Use HTTP mode when:

• Studio's agent drives MCP remotely
• a CI runner needs deterministic content operations
• an agent on another machine orchestrates content changes

HTTP sessions use the same LocalProvider backing as stdio — the transport differs, the behaviour does not. Remote git-host providers (GitHubProvider, GitLabProvider) are constructed by embedders who instantiate the MCP server programmatically; see the MCP package docs for that flow.

generate and #contentrain

contentrain generate writes a typed client to .contentrain/client/ and injects #contentrain imports into your package.json.

After generation:

import { query, singleton, dictionary, document } from '#contentrain'

Run with watch mode during local model/content work:

contentrain generate --watch

IDE Setup and AI Skills

Configure your IDE to use Contentrain's MCP server and AI agent rules:

contentrain setup claude-code
contentrain setup cursor
contentrain setup vscode
contentrain setup --all  # Configure all detected IDEs

Install or update AI agent skills and IDE rules:

contentrain skills
contentrain skills --update  # Force update
contentrain skills --list    # List installed skills

This installs:

• Contentrain Agent Skills (task guidance for Claude, Cursor, etc.)
• IDE rules files (CLAUDE.md, .cursorrules, .windsurfrules)

Review Workflow

Most write operations create feature branches from the dedicated contentrain branch. In review mode, these branches are pushed to remote for team review. In auto-merge mode, they are merged into the contentrain branch and baseBranch is advanced via update-ref.

Use:

contentrain status
contentrain diff

to understand:

• how many active cr/* review branches exist on the contentrain branch
• whether branch health is blocking new writes (warning at 50, blocked at 80)
• what changed before merging or deleting a branch

Studio Integration

The studio command group connects the CLI to Contentrain Studio for enterprise workflows.

Authenticate and connect:

contentrain studio login
contentrain studio whoami
contentrain studio connect

The connect command links your local repository to a Studio project. It detects the git remote, verifies GitHub App installation, scans for .contentrain/ configuration, and creates the project — all in one interactive flow.

contentrain studio connect --workspace ws-123

Set up CDN for content delivery:

contentrain studio cdn-init
contentrain studio cdn-build --wait

Monitor project activity and usage:

contentrain studio status
contentrain studio activity --limit 10
contentrain studio usage

Manage branches, webhooks, and form submissions:

contentrain studio branches
contentrain studio webhooks
contentrain studio submissions --form contact-form

Credentials are stored securely in ~/.contentrain/credentials.json with 0o600 permissions. Use CONTENTRAIN_STUDIO_TOKEN environment variable for CI/CD.

Documentation

Full documentation at ai.contentrain.io/packages/cli.

Development

From the monorepo root:

pnpm --filter contentrain test -- --run
pnpm --filter contentrain exec tsc --noEmit
pnpm --filter contentrain build

License

MIT