CLI reference

This is the full inventory of mx subcommands plus the hivecast wrapper commands that touch packages, grouped by lifecycle stage. Every entry links to the file where the command is defined.

The mx CLI is built from projects/matrix-3/packages/mx-cli/src/index.ts. Run mx --help for the live help text. Run <verb> --help for a specific command's flags.

Author

Command	Source	Page
mx init [-y]	commands/init.ts	Authoring → Scaffold a package
mx actor <name>	commands/actor.ts	Authoring → Scaffold a package
mx element <name>	commands/element.ts	Authoring → Scaffold a package
mx actor-element <name>	commands/actor-element.ts	Authoring → Scaffold a package
mx cqrs <name>	commands/cqrs.ts	Authoring → Scaffold a package
mx webapp <name>	commands/webapp.ts	Authoring → Scaffold a package
mx validate [target]	commands/validate.ts	Authoring → Package manifest

Build / Test

These are package-local, not mx subcommands; documented here for completeness:

Command	Where
pnpm build	per-package package.json:scripts.build
pnpm test	per-package package.json:scripts.test
pnpm build:affected / pnpm test:affected	top-level package.json (Turbo)

See Local Development → Build and Local Development → Test.

Publish

Command	Source	Page
mx pack	commands/pack.ts	Publishing → npm-compatible publication
mx publish [--dry-run]	commands/publish.ts	Publishing
mx config get/set/list/reset	commands/config.ts	Local Development → Config explain
mx login	commands/auth.ts	Publishing → npm-compatible publication
mx logout	commands/auth.ts	(auth)
mx whoami	commands/auth.ts	(auth)
mx search <query>	commands/search.ts	Publishing → Package metadata

Install / Manage

Command	Source	Page
mx install <source> [--force]	commands/install.ts	Installing
mx uninstall <packageName>	commands/uninstall.ts	Installing → Uninstall
mx list	commands/list.ts	Installing → Package store
mx info <packageName>	commands/info.ts	Installing → Package store
mx fork <packageName>	commands/fork.ts	Publishing → Versioning
mx outdated	commands/outdated.ts	Publishing → Versioning
mx update-fork <packageName>	commands/update-fork.ts	Publishing → Versioning

Run / Operate

mx run and mx up share their body in commands/run.ts:

Command	Source	Page
mx run <target> [--env <name>] [--serve] [--check]	commands/run.ts	Local Development → Run in place
mx up <target> [--env] [--serve] [--check]	commands/run.ts (alias)	Running → hivecast up
mx service <packageDir>	commands/service.ts	Authoring → Runtime entrypoints

Identity / HiveCast linking

These don't touch package state directly but commonly appear next to the package commands. Source: commands/auth.ts plus projects/matrix-3/packages/mx-cli/src/utils/hivecast-link-store.ts.

Command
mx login --hivecast [--device] [--cloud <url>]
mx logout --hivecast
mx whoami --hivecast
mx link-status
mx refresh-credentials
mx revoke-device

See projects/matrix-3/packages/docs-hivecast/content/cli/ for the HiveCast-specific narrative.

hivecast wrapper subcommands relevant to packages

The wrapper (projects/matrix-3/packages/hivecast/bin/hivecast.mjs) delegates the package-touching subcommands to the host-service CLI:

Command	What it does
hivecast up <package-or-path>	Start a runtime that supervises a package. See Running → hivecast up
hivecast down <runtime-id|package|mount>	Stop a runtime. See Running → hivecast down
hivecast invoke <mount> <op> [json]	Send a request to an actor. See Running → Verify
hivecast runtimes	List supervised runtimes. See Running → Health
hivecast status	Host status
hivecast doctor [--repair] [--json]	Audit the Host home
hivecast operator refresh-host-package	Build, install, restart in one step. See Local Development → Refresh without copying

Common flag patterns

Flag	Common across	Default
--home <path>	hivecast and matrix CLIs	~/.matrix
--packages-dir <path>	mx install/uninstall/list/info	<MATRIX_HOME>/packages
--registry <url>	mx install/publish/search	from mx config get registry
--registry-dir <path>	mx install/publish	none (mutually exclusive with --registry)
--credentials-file <path>	mx login/install/publish	<MATRIX_HOME>/credentials/registry.json
--json	most commands	off (human output)
--force	mx install	off
--check	mx run/service	off

See also

• Each lifecycle section in this site links to the commands it uses.
• Overview → Package lifecycle for the seven stages each command lives in.

Source: projects/matrix-3/packages/mx-cli/src/index.ts registers every mx subcommand; projects/matrix-3/packages/host-service/src/cli.ts registers the up/down/invoke/status/runtimes commands; projects/matrix-3/packages/hivecast/bin/hivecast.mjs:432-457 is the wrapper's help text.