mdcms init
Interactive wizard that bootstraps a new MDCMS project from an existing repository.
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
securityCLI (service:mdcms-cli), with file-based fallback - Other platforms:
~/.mdcms/credentials.jsonwith0600permissions
Authentication precedence
When resolving an API key, the CLI checks these sources in order:--api-keyflagMDCMS_API_KEYenvironment variable- 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.
mdcms push
Upload local content changes to the MDCMS server.
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
- Load manifest — Reads
.mdcms.manifest.jsonto determine which documents are tracked locally. - 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.
- New file detection — Scans content directories for untracked
.md/.mdxfiles not yet in the manifest. In interactive mode, you select which new files to upload. - Deletion detection — Files present in the manifest but missing from disk are flagged as candidates for server-side deletion.
- Plan summary — The CLI prints a summary of changes, new files, and deletions before writing anything.
- Confirmation: in a terminal, push asks for confirmation before writing unless
--yesis passed. Without a terminal it does not ask. - Execute — Changed files are uploaded, new documents are created, and deleted documents are removed on the server.
- Update manifest — The local manifest is updated with new document IDs, revision numbers, and hashes.
Concurrency control
Push uses optimistic concurrency via thedraftRevision 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.
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.
- Parses
mdcms.config.tsand resolves all type definitions - Applies environment-specific overlays if an
environmentsblock is defined in the config - Builds a schema sync payload and uploads it to the server via
PUT /api/v1/schema - Persists the returned
schemaHashto.mdcms/schema/<project>.<environment>.json
mdcms push to ensure content is validated against the correct schema version.
Overrides
Schema sync respects the standard--project and --environment global flags:
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.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:publishscope. - Schema validation, permissions and draft revision conflicts are enforced by the server.
- Read
get_schemaand pass itsschemaHashexplicitly 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 pullto update local files. Onlysync_schemaupdates 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.
- 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
mdcms migrate
Generate and apply content migrations when the schema changes.
How migrations work
- Detect schema changes — Compares the current
mdcms.config.tstypes against the server’s active schema - Generate transforms — Creates per-document migration operations (e.g. adding default values for new required fields, renaming fields)
- Preview — Without
--apply, the CLI prints a summary of what would change - 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.