CLI
@contentia/cli runs the Contentia API server from a config file, and local development workflows: a dev storage server, typed codegen from your CMS config, and content migrations between backends.
The package installs one command, contentia. Without installing anything, run it as npx @contentia/cli or pnpm dlx @contentia/cli.
Install
pnpm add -D @contentia/cli # or npm i -D / yarn add -D / bun add -dOr run without installing:
npx @contentia/cli serve --config contentia.yaml
pnpm dlx @contentia/cli local serveThe CLI needs Node.js.
At a glance
contentia serve --config contentia.yaml # the Contentia API server, from one config file
contentia hash-password # bcrypt hash for a user in the server config
contentia local serve # serve a content folder over JSON:API on :3030
contentia local mcp # the same content to AI agents, as an MCP server over stdio
contentia local generate --watch # config.yaml -> typed config.gen.ts, kept fresh on save
contentia local migrate -s ./a -d ./b # copy all content from one storage backend to another
contentia local list-backends # show the storage backends migrate can use| Command | What it does |
|---|---|
serve | Run the Contentia API from a config file (see Server Config) |
hash-password | Print the bcrypt hash of a password for auth.login.users |
local serve | Start a local-file JSON:API storage server for development |
local mcp | Expose a storage backend, or a remote Contentia API, to AI agents over MCP (stdio) |
local generate | Generate a typed TypeScript module from the CMS config file |
local migrate | Copy every folder and object from one storage backend to another |
local list-backends | List every storage backend migrate can use and its package version |
Every command accepts --help for its full flag reference, e.g. contentia local migrate --help.
local serve
Serves content as a JSON:API storage API, the same API a production API server exposes. Point an admin UI, a frontend, or any JSON:API client at it while you develop. By default it serves a folder of content files; --backend serves any storage backend migrate can use instead.
contentia local serve # serve the current directory on 127.0.0.1:3030
contentia local serve --root ./content --port 4000
contentia local serve --auth-token "$CONTENTIA_DEV_TOKEN" # require a bearer token
contentia local serve --backend webdav --backend-options '{"url":"https://dav.example.com"}'| Flag | Alias | Description |
|---|---|---|
--root | -r | Directory to serve when no --backend is given (default: the current directory) |
--default-extension | — | File extension given to newly created objects in --root (default: md) |
--backend | — | Storage backend to serve instead of --root; see contentia local list-backends |
--backend-options | — | JSON options for --backend. Falls back to the CONTENTIA_BACKEND_OPTIONS env var |
--port | -p | Port to listen on; 0 picks a free one (default: 3030) |
--host | -H | Host to listen on (default: 127.0.0.1) |
--auth-token | — | Require Authorization: Bearer <token>. Falls back to the CONTENTIA_AUTH_TOKEN env var |
--json | — | Print machine-readable events on stdout instead of log lines (see below) |
Files ending in .md/.markdown, .yaml/.yml and .json are parsed into structured content. CORS is enabled for every origin, so a dev frontend on another port can call it directly.
Backend options often hold credentials. Pass them through CONTENTIA_BACKEND_OPTIONS (and the token through CONTENTIA_AUTH_TOKEN) rather than as flags, so they don't show up in the process list.
--json output
With --json, stdout carries one JSON object per line and logs go to stderr. Editors and scripts start the server with --port 0 and wait for the listening event to learn the URL:
{"event":"listening","url":"http://127.0.0.1:54321","backend":"fs"}
{"event":"error","message":"contentia: unknown storage backend \"nope\". Available: ..."}--json also never prompts to install a missing backend package; it fails with an error event instead. The VS Code extension starts the server this way.
The server has no access control beyond the optional bearer token. It is meant for local development: keep the default 127.0.0.1 host, and use --auth-token if you bind it to a network interface. For production, run the API server.
local mcp
Runs an MCP server over stdio, for desktop clients and coding agents on your machine. It has two tools: read_api_spec reads the OpenAPI spec, and api_request calls the API.
contentia local mcp --root ./content # the storage API over a local folder, in-process
contentia local mcp --backend s3 --backend-options "$OPTIONS"
contentia local mcp --base-url https://cms.example.com/api --auth-token "$CONTENTIA_TOKEN"By default it serves the same storage API as local serve, over the same backends (--root, --default-extension, --backend, --backend-options), with no port and no access control. With --base-url it sends api_request calls to a deployed Contentia API instead, with --auth-token (or CONTENTIA_TOKEN) as the bearer token. The deployment's own authorize policy decides what the token may do.
Stdout carries the MCP protocol, so all logs go to stderr, and the command never prompts to install a backend package. It exits when the client closes stdin.
local generate
Reads your CMS config file (Decap's config.yml) and writes a TypeScript module that exports the config as an as const value. Your code gets the parsed config at runtime and literal types for every collection and field name at compile time, so a renamed field shows up as a type error.
contentia local generate # find the config, write config.gen.ts next to it
contentia local generate --watch # regenerate on every save
contentia local generate -i src/config.yml -o src/cms/config.gen.tsWithout --input, the CLI looks for config.yml, config.yaml, src/config.yml and src/config.yaml in the current directory, in that order.
| Flag | Alias | Description |
|---|---|---|
--input | -i | Path to the CMS config file (default: found automatically, see above) |
--output | -o | Path of the generated .ts file (default: config.gen.ts next to the input) |
--watch | -w | Keep running and regenerate whenever the input changes |
--cms | — | Which CMS config format to read (default: decap) |
Commit the generated file or regenerate it in your build; either works. A common setup runs contentia local generate --watch next to your dev server.
local migrate
Copies every folder and object from a source storage backend to a destination backend: filesystem to S3, WebDAV to GitHub, one folder to another, and so on. Content is read through the source's serializers and written through the destination's, so you can move between backends that store content differently.
Choosing source and destination
There are three ways to describe the two sides.
Filesystem shortcut, for copying between local folders:
contentia local migrate -s ./content -d ./backupNamed backends, with options as a JSON object:
contentia local migrate \
--source-backend fs --source-options '{"root":"./content"}' \
--destination-backend s3 \
--destination-options '{"bucket":"site-content","endpoint":"https://<account>.r2.cloudflarestorage.com"}'You can mix the two: -s ./content --destination-backend github --destination-options '{...}'.
A config file (.json, .yaml or .yml), which keeps long option sets and repeatable runs out of your shell history:
# migrate.yaml
source:
backend: fs
options:
root: ./content
destination:
backend: github
options:
owner: acme
repo: content
branch: main
commitAuthor: { name: Contentia Migration, email: bot@example.com }
migrate:
from: blog # only copy this folder and everything below it
overwrite: false
concurrency: 8GITHUB_TOKEN=ghp_... contentia local migrate --config migrate.yaml --dry-run
contentia local migrate --config migrate.yamlSettings in the file's migrate block take precedence over the matching command-line flags.
Flags
| Flag | Alias | Description |
|---|---|---|
--config | -c | JSON or YAML file with source, destination and an optional migrate block |
--source-backend | — | Source backend name (see backends) |
--source-options | — | Source backend options, as a JSON object |
--destination-backend | — | Destination backend name |
--destination-options | — | Destination backend options, as a JSON object |
--source | -s | Filesystem shortcut: source directory |
--destination | -d | Filesystem shortcut: destination directory |
--default-extension | — | Filesystem shortcut: extension for new files on the destination (default: md) |
--from | — | Folder to start from (default: the root) |
--overwrite | — | Replace objects that already exist on the destination |
--dry-run | — | Walk the source and print what would happen, without writing anything |
--concurrency | — | Objects copied in parallel per folder (default: 4) |
--page-size | — | Page size when listing source folders (default: 1000) |
--no-install | — | Fail instead of offering to install a missing backend package |
What happens during a run
- Each line of output is one folder or object:
+copied,=skipped (with the reason,existsordry-run),!failed. - Objects that already exist on the destination are skipped unless you pass
--overwrite, so re-running an interrupted migration picks up where it left off. - A failure on one object doesn't stop the run. The summary at the end counts created, skipped and failed items, and the command exits with a non-zero status when anything failed.
- Start with
--dry-runagainst a real destination to check credentials and see what would be copied. - Git-host destinations (
github,gitlab,bitbucket) make one commit per object written. Expect a long history and API rate limits on large migrations; lower--concurrencyif you hit them.
Backend packages
fs, jsonapi-proxy, webdav and github-cdn are built in. The other backends need an extra package. When it isn't installed in your project, migrate asks before installing the pinned version into ~/.contentia/backends, so your project's dependencies stay untouched. Without a terminal, or with --no-install, it fails with the install command to run yourself.
local list-backends
Prints every storage backend migrate accepts, with its package and pinned version.
contentia local list-backendsStorage backends
Options for each backend migrate accepts. Every backend that writes files also takes defaultExtension (default md). Credentials can come from the environment variables listed, so they stay out of config files and shell history. See Adapters for what each backend is and how it stores content.
| Backend | Required options | Optional options | Environment fallbacks |
|---|---|---|---|
fs | root | — | — |
jsonapi-proxy | baseUrl | authToken | — |
webdav | baseUrl | basePath, username, password, token, headers | — |
github-cdn | owner, repo | branch, fetchMeta, cdnBaseUrl, dataApiBaseUrl, userAgent | — |
s3 | bucket, accessKeyId, secretAccessKey | region (default auto), endpoint, sessionToken, keyPrefix, forcePathStyle | S3_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION, S3_ENDPOINT |
github | owner, repo, branch, plus token or GitHub App credentials | commitAuthor | GITHUB_TOKEN, GITHUB_APP_ID, GITHUB_INSTALLATION_ID, GITHUB_APP_PRIVATE_KEY |
gitlab | projectId (numeric id or URL-encoded path), branch | token, oauthToken, jobToken, apiUrl (self-hosted), commitAuthor | GITLAB_TOKEN, CI_JOB_TOKEN |
bitbucket | workspace, repo, branch, plus oauthToken or username+password | apiUrl, commitAuthor | BITBUCKET_TOKEN, BITBUCKET_USERNAME, BITBUCKET_APP_PASSWORD |
Notes:
github-cdnis read-only: use it as a source to pull content from a public repository without credentials.s3works with AWS S3, Cloudflare R2 (through its S3 endpoint), MinIO and other S3-compatible stores. For R2, setendpointand leaveregionatauto.githubaccepts either a personal access token (token) or a GitHub App:appId,installationId, and the private key asprivateKey(PEM string) orprivateKeyPath.shcontentia local migrate -s ./content --destination-backend github --destination-options \ '{"appId":"123","installationId":"456","privateKeyPath":"./app.pem","owner":"acme","repo":"content","branch":"main"}'commitAuthoris an object:{ "name": "...", "email": "..." }.
Programmatic API
Everything the CLI does is also exported from the package, for use in your own scripts:
import { generateConfig, layerStorageServer, runMigrate } from '@contentia/cli';
// Run a migration from a script, with your own progress handling
const result = await runMigrate({
config: {
source: { backend: 'fs', options: { root: './content' } },
destination: { backend: 'fs', options: { root: './backup' } },
migrate: { dryRun: true },
},
onEvent: event => console.log(event.type, 'key' in event ? event.key : ''),
});
console.log(`${result.objectsCopied} copied, ${result.errors.length} errors`);| Export | Use it to |
|---|---|
layerStorageServer | Serve any storage repository the way local serve does |
buildLocalMcpServer, runMcpStdioServer | Build and run the MCP server the way local mcp does |
generateConfig, loadConfig | Generate or load the typed CMS config |
runMigrate, loadMigrateConfig | Run a migration from a config object or file |
migrateStorage | Copy between two storage repositories you already constructed |
storageDrivers, buildStorageRepository | Look up a storage backend by name and build it from options |
If you build your own CLI with Effect, the make*Command factories (makeServeCommand, makeGenerateCommand, makeMigrateCommand, …) let you mount these commands under your own names.