CLI reference

Two command surfaces, deliberately mirrored. mx works from anywhere and knows about global state: templates, recipes, the router. make works inside a project and is the same in every project. Where they overlap (dev, up, down, logs, sh, ps, build), they do the same thing.

Everything below is transcribed from mx --help, mx <verb> --help and make help against the current build. Ask any of them yourself. They are the authority, this page is a map.

mx

mx [OPTIONS] <COMMAND>

Options:
  -v, --verbose  Enable verbose output
  -h, --help     Print help
  -V, --version  Print version

Scaffolding

Command	Purpose
mx init	Install templates to ~/.mech-crate. --force to overwrite, --update to refresh templates and keep config
mx new <NAME>	Create a project. --with <SERVICE> (repeatable), --infra <PROVIDER>, --no-prompt
mx add <NAME>	Add a service. --recipe <RECIPE>, --domain <DOMAIN>, --opt <KEY=VALUE>
mx recipes list | ls	List available recipes
mx recipes info <NAME>	Recipe description, features, options, services
mx recipes apply <NAME>	Apply a recipe to the current project
mx recipes versions <NAME>	List available versions for a recipe
mx recipes pull <NAME>	Pull a recipe from Unyform
mx recipes cache	Manage cached recipes
mx upgrade	Upgrade project scaffolding. --diff, --dry-run, --yes. See Upgrade
mx self-update	Update mx itself from the release channel. --check (exit 10 when newer exists), --dry-run, --yes, --to <VERSION>, --rollback, --from-dir <DIR>, --pull for source checkouts. See Install

Operating a project

All of these take an optional [SERVICE] and support -f/--follow and -v/--verbose:

Command	Purpose
mx dev [SERVICE]	Start the development environment
mx up [SERVICE]	Start services in production mode
mx down [SERVICE]	Stop services
mx restart [SERVICE]	Restart a service
mx logs [SERVICE]	View service logs
mx sh [SERVICE]	Open a shell in a service container
mx ps [SERVICE]	List running services

mx build <SERVICE> requires the service name and takes --prod, --dev, -t/--tag <TAG>, --push, --no-cache, --platform <PLATFORM>.

mx doctor checks project health and exits non-zero on a failed check.

Router

mx router install | up | down | restart | status | logs | inspect | network | uninstall

start aliases up, stop aliases down, ps aliases status, info aliases inspect, and remove aliases uninstall. Detail on The router.

Infrastructure

mx infra setup [PROVIDER] | list | inspect | link | unlink | remove

ls aliases list. See Infra credentials.

AI layer

Command	Purpose
mx mcp build	Build the MCP server binaries
mx mcp status | ps	Corpus backend and counts
mx mcp config	Print MCP client configuration
mx mcp run	Run the MCP server interactively
mx mcp info / mx mcp test	Server info / smoke test
mx rag ingest	Ingest technique docs into the corpus
mx rag status	Backend, doc/chunk counts, embedding model
mx rag gaps	Mine research-gap themes from weak-scoring queries

More on AI Layer.

Documents

mx docs [INPUT] compiles Markdown to PDF/HTML. It takes a file or a directory and has a large flag surface: --output, --title, --author, --theme, --order, --markdown-only, --html-only, --no-toc, --no-recursive, --logo, --company-name, plus a docs.json config mode (--config, --list, --all, --doc). Run mx docs --help for the full list, and see the corpus guide: mx docs.

Unyform

mx login, mx logout, mx whoami, and the same three under mx unyform login | logout | whoami. mx cc-plugin installs or uninstalls the Unyform Claude Code plugin hooks. All optional; see Remote blueprints.

make

Every scaffolded project ships these. make help prints them with descriptions. Two conventions run through all of them:

• s=<service> (or service=<service>) selects what to act on. Verbs that operate on the whole stack treat it as optional; restart requires it. Where the compose verb underneath takes several service operands, s= takes a whitespace-separated list in quotes: make dev s="api site". The quotes are required, because make otherwise reads the second name as another goal.
• t=<tag>, c=<command>, a=<app> follow the same short/long pattern (tag=, cmd=, …).

Which verbs take a list is decided by the verb underneath rather than by taste:

s= accepts	Verbs
a list	dev, up, down, stop, restart, logs
one service	build, build-dev, build-prod, build-multiplatform, run, exec, sh, bash

A single-service verb handed a list refuses out loud (make build takes a single service only) rather than silently acting on the first name. An unknown name anywhere in a list fails and names it.

Target	Purpose
make help	Show available commands
make init	Initialize project environment (creates .env.secrets from the template, then generates any value still missing)
make doctor	Check project health
make test	Run the project’s tests
make ps	List running services
make dev	Start services in dev mode (s="[service ...]" for a subset)
make up	Start services in production mode (s="[service ...]" for a subset)
make down	Stop and remove services (s="[service ...]" for a subset)
make stop	Stop services without removing (s="[service ...]" for a subset)
make start	Resume services from saved state
make restart	Restart services (s="[service ...]" required)
make logs	Tail service logs (s="[service ...]" for a subset)
make sh / make bash	Shell into a running service (s=[service], one service)
make exec	Exec a command in a running container (s=[service] c=[cmd], one service)
make run	Run a command in a new container (s=[service] c=[cmd], one service)
make build	Build an image (s=[service] t=[tag] prod=[0|1] push=[0|1], one service)
make build-dev / make build-prod	Build one image variant explicitly (one service)
make build-multiplatform	Multi-platform production build (one service)
make make-key	Generate a secret (BYTES=32 FORMAT=hex|base64|uuid)

c= takes a single word

make exec s=api c=bash works. A multi-word command (c="ls -la") is split by make and the extra words are read as targets. Shell into the container with make sh s=api and run it there instead.

s= is a service name, not a container name

s=db is the service. The container behind it is named by Compose as <COMPOSE_PROJECT_NAME>-db-1, because no shipped compose file pins container_name any more. A script that reached past these verbs with docker exec db … no longer resolves; use make exec s=db c=…, or docker compose -p "$COMPOSE_PROJECT_NAME" exec db …. See Compose & env conventions.

Release targets (make release, release-patch, release-minor, release-major, release-dry, release-first, release-simple*, release-push, release-full, release-sync, release-changelog, release-version, release-list-apps) all take app=[app] and drive the per-app version/tag flow.

Cloudflare targets (cf-setup, cf-deploy, cf-logs, …) exist only in projects created with --infra cloudflare; they are listed on Cloudflare deploy.

Developing mx itself

The repository’s own Makefile is a different surface: make build, make test, make lint, make check, make coverage, make test-known-broken, make test-e2e, make test-mutants, make install-local. See Testing, and the corpus cards: MechCrate CLI Quick Reference and MX Rust CLI & MCP Server Quick Reference.