Skip to content

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 ​

sh
pnpm add -D @contentia/cli   # or npm i -D / yarn add -D / bun add -d

Or run without installing:

sh
npx @contentia/cli serve --config contentia.yaml
pnpm dlx @contentia/cli local serve

The CLI needs Node.js.

At a glance ​

sh
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
CommandWhat it does
serveRun the Contentia API from a config file (see Server Config)
hash-passwordPrint the bcrypt hash of a password for auth.login.users
local serveStart a local-file JSON:API storage server for development
local mcpExpose a storage backend, or a remote Contentia API, to AI agents over MCP (stdio)
local generateGenerate a typed TypeScript module from the CMS config file
local migrateCopy every folder and object from one storage backend to another
local list-backendsList 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.

sh
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"}'
FlagAliasDescription
--root-rDirectory 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-pPort to listen on; 0 picks a free one (default: 3030)
--host-HHost 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:

json
{"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.

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

sh
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.ts

Without --input, the CLI looks for config.yml, config.yaml, src/config.yml and src/config.yaml in the current directory, in that order.

FlagAliasDescription
--input-iPath to the CMS config file (default: found automatically, see above)
--output-oPath of the generated .ts file (default: config.gen.ts next to the input)
--watch-wKeep 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:

sh
contentia local migrate -s ./content -d ./backup

Named backends, with options as a JSON object:

sh
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:

yaml
# 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: 8
sh
GITHUB_TOKEN=ghp_... contentia local migrate --config migrate.yaml --dry-run
contentia local migrate --config migrate.yaml

Settings in the file's migrate block take precedence over the matching command-line flags.

Flags ​

FlagAliasDescription
--config-cJSON 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-sFilesystem shortcut: source directory
--destination-dFilesystem 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, exists or dry-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-run against 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 --concurrency if 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.

sh
contentia local list-backends

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

BackendRequired optionsOptional optionsEnvironment fallbacks
fsroot——
jsonapi-proxybaseUrlauthToken—
webdavbaseUrlbasePath, username, password, token, headers—
github-cdnowner, repobranch, fetchMeta, cdnBaseUrl, dataApiBaseUrl, userAgent—
s3bucket, accessKeyId, secretAccessKeyregion (default auto), endpoint, sessionToken, keyPrefix, forcePathStyleS3_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION, S3_ENDPOINT
githubowner, repo, branch, plus token or GitHub App credentialscommitAuthorGITHUB_TOKEN, GITHUB_APP_ID, GITHUB_INSTALLATION_ID, GITHUB_APP_PRIVATE_KEY
gitlabprojectId (numeric id or URL-encoded path), branchtoken, oauthToken, jobToken, apiUrl (self-hosted), commitAuthorGITLAB_TOKEN, CI_JOB_TOKEN
bitbucketworkspace, repo, branch, plus oauthToken or username+passwordapiUrl, commitAuthorBITBUCKET_TOKEN, BITBUCKET_USERNAME, BITBUCKET_APP_PASSWORD

Notes:

  • github-cdn is read-only: use it as a source to pull content from a public repository without credentials.

  • s3 works with AWS S3, Cloudflare R2 (through its S3 endpoint), MinIO and other S3-compatible stores. For R2, set endpoint and leave region at auto.

  • github accepts either a personal access token (token) or a GitHub App: appId, installationId, and the private key as privateKey (PEM string) or privateKeyPath.

    sh
    contentia local migrate -s ./content --destination-backend github --destination-options \
      '{"appId":"123","installationId":"456","privateKeyPath":"./app.pem","owner":"acme","repo":"content","branch":"main"}'
  • commitAuthor is an object: { "name": "...", "email": "..." }.

Programmatic API ​

Everything the CLI does is also exported from the package, for use in your own scripts:

ts
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`);
ExportUse it to
layerStorageServerServe any storage repository the way local serve does
buildLocalMcpServer, runMcpStdioServerBuild and run the MCP server the way local mcp does
generateConfig, loadConfigGenerate or load the typed CMS config
runMigrate, loadMigrateConfigRun a migration from a config object or file
migrateStorageCopy between two storage repositories you already constructed
storageDrivers, buildStorageRepositoryLook 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.