Skip to main content

Set up MDCMS automatically — paste this into Claude Code, Codex, or any AI coding agent

CursorOpen in Cursor
The MDCMS CLI lets you sync content and schema between your local filesystem and the MDCMS server. It handles authentication, push/pull workflows, and CI/CD integration.

​
Install

npm install --save-dev @mdcms/cli
Or install globally to use the mdcms command directly: 
npm install -g @mdcms/cli
The binary name is mdcms. If installed as a project dependency, use your package manager’s runner: 
npx mdcms --help
# or
bunx mdcms --help

​
Prerequisites

  • Node.js 20+ or Bun 1.3.11+
  • A running MDCMS server instance

​
First-time setup

The mdcms init command walks you through an interactive wizard that configures everything needed to start managing content.
1

Run the init wizard

mdcms init
2

Enter server URL

Provide the URL of your MDCMS server (e.g. https://cms.example.com). The CLI validates the connection with a health check before proceeding.
3

Choose project and environment

Select an existing project or create a new one, then choose the target environment (e.g. development, staging, production).
4

Authenticate via browser

The CLI opens your default browser for OAuth authentication using a device flow. Complete the login in your browser and the CLI receives credentials automatically.
5

Auto-detect content directories and locales

The wizard scans your repository for Markdown and MDX files, groups them by directory, and detects locale patterns from file names (e.g. post.en.mdx, post.fr.mdx).
6

Generate mdcms.config.ts

A configuration file is generated at the project root with your project settings, content type definitions inferred from existing files, and locale configuration.
7

Initial schema sync and content push

The inferred schema is synced to the server, and all discovered content files are pushed as initial draft documents.
8

.gitignore update

The wizard appends managed files (manifest, schema state) to your .gitignore and untracks them from git with git rm -r --cached if they were previously committed.

​
Global options

Every command accepts these flags:
FlagDescription
--project <slug>Override the target project slug
--environment <name>Override the target environment name
--api-key <token>Provide an API key directly (useful for CI)
--server-url <url>Override the server URL from config
--config <path>Path to config file (default: mdcms.config.ts)
-V, --versionPrint installed CLI version and exit
-h, --helpShow help text

​
Resolution order

When the CLI needs a value for project, environment, server URL, or API key, it resolves from the highest-priority source first:
  1. CLI flags — --project, --environment, --api-key, --server-url
  2. Environment variables — MDCMS_PROJECT, MDCMS_ENVIRONMENT, MDCMS_API_KEY, MDCMS_SERVER_URL
  3. Config file — values from mdcms.config.ts
  4. Stored credentials — API key from the local credential store (set by mdcms login)
CLI flags always win. This makes it straightforward to override config values in CI pipelines or when working across multiple environments.