Command line

This page lists the commands of @micacms/editor (the local editor) and of the self-hosted image. A command or option without a version exists since 0.2.0.

The local editor

Install the editor in the project with npm install --save-dev @micacms/editor, then run each command with npx mica <command>. Before it is installed, npx @micacms/editor <command> does the same. npx mica --help shows the same list.

A path without an option is always the content root. Each command takes only its own options, and refuses the others with exit code 64.

The content root is the path that you give, or MICA_CONTENT_ROOT, or the directory with a .mica/schema.json, or ./content, in this order. Mica looks for .mica/schema.json at most three levels below the current directory, and not in node_modules or a hidden directory. If it finds more than one, give the path.

start

npx mica start [content dir]

Opens the editor on this machine. It has no sign-in, and it listens only on loopback.

start stops with exit code 64 when the content directory does not exist, and with 78 when .mica/schema.json is missing. Run npx astro sync to write the model.

From 0.10.0, start also serves the tools for coding agents at http://localhost:<port>/mcp. See Edit with an agent.

init

Added in 0.5.0.

npx mica init

Adds Mica to the Astro project in the current directory. It writes a starter model in src/mica.ts and the collections in src/content.config.ts. Then it tells you which scripts (mica, check) to set in package.json. It never overwrites a file. It takes no options.

check

Added in 0.5.0.

npx mica check [content dir]

Checks every entry against the model: fields that do not validate, missing media, relations to entries that do not exist, and files that Mica does not read. It prints each problem. It exits with 0 when there is no error, 1 when there is one, and 78 when it cannot read the model.

import

Added in 0.6.0.

npx mica import [content dir] [options]

Moves Astro content collections into Mica, from Astro's data store. Without --collection, it imports every collection that the model defines. It exits with 78 when it cannot read the model. See Add Mica to an existing site.

mcp

Added in 0.10.0.

npx mica mcp [content dir] [options]

Serves the tools for coding agents over stdio, without the editor. The agent starts this command itself: put it in the agent's MCP configuration. It writes its log to stderr. When you start it in a terminal yourself, it shows the configuration to give to your agent. start shows the same for its /mcp address. See Edit with an agent.

mcp stops with the same exit codes as start when there is no content directory or no model.

Exit codes

The self-hosted image

Without a command, or with serve, the image serves the editor. check tests the configuration, and compact makes the clone small again. Another command exits with 64.

check

Added in 0.5.0.

docker compose run --rm mica check

Tests the configuration in a temporary clone, while the server can run:

• the configuration loads;
• the identity provider answers discovery, with the configured issuer. The line also shows the redirect URI to register;
• the token can read the branch;
• the token may push (a dry run, which cannot see branch protection or server hooks);
• the content root, and its model at .mica/schema.json loads;
• Git LFS is not used under the content root;
• the data volume is writable and has a layout that this version knows. If there is a clone, the line shows its head, the number of drafts, a commit that is not pushed, and work that the next start finishes.

It prints one line for each check, ok or FAIL, and exits with 0 when all pass, 1 when a check fails, and 78 when the configuration does not load. The settings are in Configuration. The endpoints are in Health endpoints.

compact

docker compose stop mica
docker compose run --rm mica compact
docker compose start mica

Makes a new clone on the data volume, with only the current files. The clone grows with each media change on the website, and a new clone is often much smaller. It refuses a clone with drafts or with a publication that is not pushed yet: start Mica, publish or discard them, and stop it again. While another Mica uses the volume, it waits up to 45 seconds, then refuses. It exits with 0 when it compacted the clone or found none, 1 when the clone holds work, and 78 when the configuration does not load or another Mica uses the volume.