Skip to main content

mdcms init

Interactive wizard that bootstraps a new MDCMS project from an existing repository.
The wizard runs through the following steps:
1

Server URL

Prompts for the MDCMS server URL and validates it with a health check.
2

Project selection

Lists existing projects on the server or creates a new one.
3

OAuth login

Opens a browser window for authentication using the device flow (same mechanism as mdcms login).
4

Environment selection

Choose an existing environment or create one (e.g. development, staging).
5

Directory scanning

Recursively scans the repository for .md and .mdx files and groups them by top-level content directories.
6

Locale detection

Analyzes file naming patterns to detect locale suffixes (e.g. post.en.mdx, post.fr.mdx) and infers default/supported locale configuration.
7

Schema inference

Parses frontmatter from discovered files to infer content types and their field schemas using Zod types.
8

Config generation

Writes mdcms.config.ts with defineConfig and defineType calls reflecting all discovered types, directories, and locale settings.
9

Schema sync

Uploads the inferred schema to the server for the selected project/environment.
10

Content push

Pushes all discovered content files to the server as draft documents and writes the initial manifest.
11

.gitignore update

Appends .mdcms/ and manifest paths to .gitignore.
12

Untrack managed files

Runs git rm -r --cached on any managed files that were previously committed to git.
Running mdcms init in a repository that already has an mdcms.config.ts will prompt before overwriting.

mdcms login

Authenticate with the MDCMS server using a browser-based OAuth flow and store credentials locally.
1

Start challenge

The CLI sends a login challenge to the server with a cryptographic state parameter and a loopback redirect URI.
2

Browser authentication

Your default browser opens the server’s authorization page. Complete the login there.
3

Receive callback

The CLI listens on a local port for the OAuth callback. The browser redirects back with an authorization code.
4

Exchange for API key

The CLI exchanges the authorization code for a scoped API key.
5

Store credentials

The API key is stored in the local credential store, scoped to the current server/project/environment tuple.

Credential storage

Credentials are stored per server/project/environment combination:
  • macOS: OS Keychain via the security CLI (service: mdcms-cli), with file-based fallback
  • Other platforms: ~/.mdcms/credentials.json with 0600 permissions

Authentication precedence

When resolving an API key, the CLI checks these sources in order:
  1. --api-key flag
  2. MDCMS_API_KEY environment variable
  3. Stored credential profile (from mdcms login)

Default scopes

The login flow requests the following scopes:

mdcms logout

Revoke the stored API key and clear local credentials for the current server/project/environment tuple.
The CLI attempts to revoke the API key on the server as a best-effort operation. Even if the remote revocation fails (e.g. the server is unreachable), the local credential profile is always removed.

mdcms push

Upload local content changes to the MDCMS server.
Preview a push with mdcms push --dry-run: it prints the plan and writes nothing. --yes (or --force) does not override conflicts. Stale draft revisions, path conflicts, and schema mismatches fail with or without it. Without a terminal (CI, scripts, agents), push does not prompt: changed tracked files are pushed as drafts right away, and new and deleted files are skipped unless you pass --yes.

How push works

  1. Load manifest — Reads .mdcms.manifest.json to determine which documents are tracked locally.
  2. Hash-based change detection — Computes a content hash for each tracked file and compares against the manifest. Only changed files are included in the push plan.
  3. New file detection — Scans content directories for untracked .md/.mdx files not yet in the manifest. In interactive mode, you select which new files to upload.
  4. Deletion detection — Files present in the manifest but missing from disk are flagged as candidates for server-side deletion.
  5. Plan summary — The CLI prints a summary of changes, new files, and deletions before writing anything.
  6. Confirmation: in a terminal, push asks for confirmation before writing unless --yes is passed. Without a terminal it does not ask.
  7. Execute — Changed files are uploaded, new documents are created, and deleted documents are removed on the server.
  8. Update manifest — The local manifest is updated with new document IDs, revision numbers, and hashes.

Concurrency control

Push uses optimistic concurrency via the draftRevision field. If the server’s current revision does not match the manifest’s recorded revision, the push for that document is rejected. Run mdcms pull to reconcile before retrying.
Push requires a valid schema hash from a previous mdcms schema sync. If the schema has never been synced or the local hash is missing, the command will fail.

mdcms pull

Download content from the MDCMS server to your local filesystem.

Change categories

The pull command classifies each document into one of these categories:
Use --force to skip confirmation prompts in non-interactive environments (e.g. CI pipelines). Locally modified files will be overwritten.

mdcms schema sync

Upload the local schema definition to the MDCMS server.
This command:
  1. Parses mdcms.config.ts and resolves all type definitions
  2. Applies environment-specific overlays if an environments block is defined in the config
  3. Builds a schema sync payload and uploads it to the server via PUT /api/v1/schema
  4. Persists the returned schemaHash to .mdcms/schema/<project>.<environment>.json
The schema hash is required by mdcms push to ensure content is validated against the correct schema version.

Overrides

Schema sync respects the standard --project and --environment global flags:
At least one content type must be defined in mdcms.config.ts before running schema sync. The command will fail with a NO_TYPES_DEFINED error if the types array is empty.

mdcms mcp

Run a Model Context Protocol server over stdio so an AI agent can read and change content in the configured project and environment.
mdcms mcp is a preview. The tool surface may change between minor releases.
The server uses the same server URL, project, environment, and credentials as every other command, so run mdcms login (or set MDCMS_API_KEY) first. The key from mdcms login or mdcms init has the default scopes, which cover common content and schema operations but exclude publishing and additional media, environment, and webhook scopes. If the server rejects the key (401), stderr directs the user to run mdcms login or set MDCMS_API_KEY; restart the MCP server afterwards, because it reads the key at startup. Register it with your agent client from the project root:

Tools and connection requirements

Use Node.js 24.11.1 or later and an MDCMS server with /api/v1/mcp enabled. The CLI forwards the remote registry, including tool schemas, annotations, results and errors. Tool discovery reflects server capabilities and the credential’s permissions. sync_schema is a local tool and requires schema:write. It reloads the resolved mdcms.config.ts, syncs to the original connection, and returns schemaHash, syncedAt and affectedTypes. Restart the bridge to change its server, project, environment or credentials. get_credentials_info is a read-only local diagnostic for the resolved target, capability-derived scopes, and common content/schema tool scope requirements. Its allowed flags do not guarantee path access or describe the complete remote inventory. Remote discovery remains authoritative. Login/init keys exclude publishing; supply a Studio-created key with content:publish to publish. After replacing a rejected key, restart the bridge.

How writes behave

  • Create and update operate on drafts. Publishing requires a separate tool and the content:publish scope.
  • Schema validation, permissions and draft revision conflicts are enforced by the server.
  • Read get_schema and pass its schemaHash explicitly to write tools that require it. After a schema change, review the schema before acknowledging the new hash. The bridge never substitutes local schema state or refreshes the hash automatically.
  • Remote tool writes affect server content. Run mdcms pull to update local files. Only sync_schema updates local schema state.
  • A transport failure may leave a mutation’s outcome unknown. The bridge does not retry it; inspect server state before retrying.
  • stdout carries JSON-RPC only. Diagnostics use stderr, and closing stdin closes the connection.

mdcms status

Compare local content and schema state against the server.
The status command reports:
  • Content drift — Documents that have been modified locally, modified on the server, or are out of sync
  • Schema drift — Whether the local schema hash matches the server’s current schema

Drift categories

Moves are shown as <local path> -> <path after mdcms pull>. When only the extension differs, the server inferred a different format from the body (for example, a .mdx file with no MDX syntax is stored as md), and mdcms pull renames the local file. Documents whose type is not in your local config are skipped with a warning, as mdcms pull skips them.

Exit codes

Use mdcms status in CI pipelines as a gate. A non-zero exit code can block deployments when content or schema is out of sync.

mdcms migrate

Generate and apply content migrations when the schema changes.

How migrations work

  1. Detect schema changes — Compares the current mdcms.config.ts types against the server’s active schema
  2. Generate transforms — Creates per-document migration operations (e.g. adding default values for new required fields, renaming fields)
  3. Preview — Without --apply, the CLI prints a summary of what would change
  4. Apply — With --apply, each document is transformed and pushed as a new draft revision. If the document was previously published, a new version is auto-published
Migrations are forward-only. Always review the preview output before running with --apply.