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.

​
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 — Destructive changes (deletions, overwrites) require explicit confirmation unless --force is passed.
  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 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

​
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.