CLI Reference¶

This document provides a reference for the MAID command-line interface (CLI).

Overview¶

The MAID CLI is built with Typer and provides commands for server management, development, and administration.

General Usage:

uv run maid [OPTIONS] COMMAND [ARGS]...

Getting Help:

uv run maid --help
uv run maid COMMAND --help

Command Groups¶

Group	Description
`server`	Server lifecycle management
`db`	Database migration and management
`data`	Content data loading, validation, migration, and schema inspection
`content`	Content pack management
`dev`	Development tools
`api`	API key management
`plugin`	Plugin development, quality, and registry commands
`pack`	Content pack hot reload management
`quickstart`	Scaffold new content pack projects
`batch`	Batch processing commands
`i18n`	Internationalization commands
`docs`	Documentation generation commands
`world`	World management commands
`ai`	AI provider management commands
`ops`	Operator control-plane verbs (many stubs pending control plane; visible in `uv run maid --help`)
`status`	Show deploy contract/liveness info; can render a static status page

Standalone Commands¶

Command	Description
`maid validate`	Validate a content pack before server start
`maid version`	Show MAID version

Root Commands¶

maid validate¶

Validate a content pack before server start. Runs all checks (manifest, protocol, dependencies, YAML content, commands, orphan detection, import) and produces a summary report.

uv run maid validate PACK_PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PACK_PATH`	path	Yes	Path to content pack directory

Options:

Option	Type	Default	Description
`--json`, `-j`	flag	false	Output as JSON

Exit codes: 0 = all pass, 1 = errors found, 2 = only warnings.

Examples:

uv run maid validate ./packages/maid-stdlib
uv run maid validate ./my-pack --json

maid version¶

Show MAID version.

uv run maid version

Server Commands¶

maid server start¶

Start the MAID server.

uv run maid server start [OPTIONS]

Options:

Option	Type	Default	Description
`--config`, `-c`	path	—	Path to configuration file
`--host`, `-h`	str	`0.0.0.0`	Host to bind to
`--telnet-port`, `-t`	int	`4000`	Telnet port
`--web-port`, `-w`	int	`8080`	Web/API port
`--debug`, `-d`	flag	false	Enable debug mode
`--watch`	flag	false	Enable file watching for hot reload during development
`--watch-debounce`	float	`0.5`	Debounce delay in seconds for file watching
`--content`	str	—	Content packs to load (can be repeated)

Examples:

# Start with defaults
uv run maid server start

# Start with custom ports
uv run maid server start --telnet-port 5000 --web-port 8888

# Start in debug mode with hot reload
uv run maid server start --debug --watch

# Start with specific content packs
uv run maid server start --content maid-stdlib --content my-pack

# Start with a config file
uv run maid server start --config /path/to/config.toml

maid server status¶

Show server status (if running).

uv run maid server status

maid server stop¶

Stop the running server.

uv run maid server stop

API Key Commands¶

The api command group manages API keys for external integrations.

maid api generate-key¶

Generate a new API key.

uv run maid api generate-key [OPTIONS]

Options:

Option	Type	Required	Description
`--name`, `-n`	str	Yes	Human-readable name for the key
`--permissions`, `-p`	str	No	Comma-separated permissions (default: `read-public`)
`--expires`, `-e`	str	No	Expiration duration (e.g., `30d`, `24h`, `60m`). No expiration if omitted
`--rate-limit`, `-r`	int	No	Requests per minute (default: 60)
`--created-by`, `-c`	str	No	Identifier of who/what is creating this key (default: `cli`)
`--store`, `-s`	path	No	Path to API key store file
`--json`	flag	No	Output as JSON

Available Permissions:

Permission	Description
`read-public`	Read public server information
`read-players`	Read player data
`write-players`	Modify player data
`read-world`	Read world data (rooms, NPCs, items)
`write-world`	Modify world data
`admin`	Administrative actions

Permission Shortcuts:

Shortcut	Expands To
`read-all`	`read-public,read-players,read-world`
`write-all`	`write-players,write-world`
`full-access`	All permissions

Examples:

# Create a read-only key
uv run maid api generate-key --name "Dashboard" --permissions read-public,read-players

# Create an admin key with expiration
uv run maid api generate-key --name "Admin Bot" --permissions admin --expires 30d

# Create a key with custom rate limit
uv run maid api generate-key --name "High Traffic" --permissions read-all --rate-limit 200

# Create a full-access key
uv run maid api generate-key --name "Super Bot" --permissions full-access

Output:

API Key created successfully!
Key ID: 550e8400-e29b-41d4-a716-446655440000
Name: Dashboard
Permissions: read-public, read-players
Rate Limit: 60 requests/minute
Expires: Never

IMPORTANT: Save this key now - it cannot be retrieved later!
API Key: maid_550e8400_AbCdEfGhIjKlMnOpQrStUvWxYz123456

maid api list-keys¶

List all API keys.

uv run maid api list-keys [OPTIONS]

Options:

Option	Type	Default	Description
`--all`, `-a`	flag	false	Include revoked keys
`--store`, `-s`	path	—	Path to API key store file
`--json`	flag	false	Output as JSON

Examples:

# List active keys in table format
uv run maid api list-keys

# List all keys including revoked
uv run maid api list-keys --all

# Output as JSON
uv run maid api list-keys --json

Output (Table):

API Keys (5 active)
================================================================================
KEY ID                                NAME             PERMISSIONS      LAST USED
--------------------------------------------------------------------------------
550e8400-e29b-41d4-a716-446655440000  Dashboard        read-public...   2024-01-20
660e8400-e29b-41d4-a716-446655440001  Admin Bot        admin            2024-01-19
770e8400-e29b-41d4-a716-446655440002  Discord Bot      read-all         Never
================================================================================

Output (JSON):

{
  "keys": [
    {
      "key_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Dashboard",
      "permissions": ["read-public", "read-players"],
      "created_at": "2024-01-15T10:30:00Z",
      "expires_at": null,
      "last_used": "2024-01-20T15:45:00Z",
      "is_active": true,
      "rate_limit_rpm": 60
    }
  ],
  "total": 5
}

maid api revoke-key¶

Revoke an API key.

uv run maid api revoke-key KEY_ID [OPTIONS]

Arguments:

Argument	Type	Required	Description
`KEY_ID`	str	Yes	UUID of the key to revoke

Options:

Option	Type	Default	Description
`--store`, `-s`	path	`data/api_keys.json`	Path to API key store file
`--force`, `-f`	flag	false	Skip confirmation prompt
`--json`	flag	false	Output as JSON

Examples:

# Revoke with confirmation
uv run maid api revoke-key 550e8400-e29b-41d4-a716-446655440000

# Revoke without confirmation
uv run maid api revoke-key 550e8400-e29b-41d4-a716-446655440000 --force

Output:

Revoking API key:
  Key ID: 550e8400-e29b-41d4-a716-446655440000
  Name: Dashboard
  Permissions: read-public, read-players

Are you sure? This action cannot be undone. [y/N]: y

API key revoked successfully.

maid api info¶

Show information about a specific API key.

uv run maid api info KEY_ID [OPTIONS]

Arguments:

Argument	Type	Required	Description
`KEY_ID`	str	Yes	UUID of the key

Options:

Option	Type	Default	Description
`--store`, `-s`	path	`data/api_keys.json`	Path to API key store file
`--json`	flag	false	Output as JSON

Examples:

uv run maid api info 550e8400-e29b-41d4-a716-446655440000

Output:

API Key Information
================================================================================
Key ID:        550e8400-e29b-41d4-a716-446655440000
Name:          Dashboard
Status:        Active
Permissions:   read-public, read-players
Rate Limit:    60 requests/minute
Created:       2024-01-15 10:30:00 UTC
Created By:    admin
Expires:       Never
Last Used:     2024-01-20 15:45:00 UTC
================================================================================

Development Commands¶

maid dev shell¶

Start an interactive Python shell with MAID loaded.

uv run maid dev shell

Available in shell:

maid_engine - The maid_engine module
get_settings - Settings accessor function
Entity - The Entity class
World - The World class
discover_content_packs - Content pack discovery function

maid dev test-ai¶

Test an AI provider with a prompt.

uv run maid dev test-ai "Your prompt here" [OPTIONS]

Options:

Option	Type	Default	Description
`--provider`, `-p`	str	(settings-driven)	AI provider to use

Examples:

# Test with default provider (from settings)
uv run maid dev test-ai "Tell me a short story"

# Test with specific provider
uv run maid dev test-ai "Hello!" --provider ollama

maid dev profile¶

Run profiling for a specified duration.

uv run maid dev profile [OPTIONS]

Options:

Option	Type	Default	Description
`--types`, `-t`	str	`memory,tick`	Profiling types: memory, tick, query, network (comma-separated)
`--duration`, `-d`	int	`60`	Duration in seconds
`--output`, `-o`	path	—	Output file for report (supports .html, .json, .txt)
`--json`	flag	false	Output as JSON to stdout

Examples:

uv run maid dev profile --types=memory,tick --duration=60
uv run maid dev profile -t memory -d 30 -o report.html

maid dev memory-snapshot¶

Take a memory snapshot of the current process.

uv run maid dev memory-snapshot [OPTIONS]

Options:

Option	Type	Default	Description
`--output`, `-o`	path	—	Output file for snapshot
`--depth`	int	`10`	Stack trace depth
`--top`, `-n`	int	`20`	Number of top allocations to show

Examples:

uv run maid dev memory-snapshot
uv run maid dev memory-snapshot -o snapshot.json -n 50

maid dev info¶

Show MAID version and configuration info.

uv run maid dev info

maid dev reload¶

Hot reload modules, packs, or systems.

uv run maid dev reload TARGET [OPTIONS]

Arguments:

Argument	Type	Required	Description
`TARGET`	str	Yes	Target to reload (module, pack, or system name)

Options:

Option	Type	Default	Description
`--type`, `-t`	str	`module`	Type of target: module, pack, system
`--cascade/--no-cascade`	flag	cascade	Cascade reload to dependents
`--watch`, `-w`	flag	false	Watch mode — auto-reload on file changes
`--watch-path`, `-p`	str	—	Paths to watch (can be repeated)
`--debounce`, `-d`	float	`0.5`	Debounce delay in seconds for watch mode

Examples:

# Reload a module
uv run maid dev reload maid_engine.core.world

# Reload a content pack
uv run maid dev reload maid-classic-rpg --type pack

# Watch mode with auto-reload
uv run maid dev reload maid_engine --type module --watch --watch-path src/maid_engine/

maid dev reload-status¶

Show reload manager status and statistics.

uv run maid dev reload-status

maid dev watch¶

Start the server and auto-reload a content pack on file changes.

uv run maid dev watch [OPTIONS]

Options:

Option	Type	Default	Description
`--pack`, `-p`	path	required	Content pack directory to watch
`--port`	int	`4000`	Telnet port
`--poll-interval`	float	`1.0`	Polling interval in seconds (fallback mode)
`--include`	str	`.py,.yaml,*.yml`	Comma-separated file patterns to watch

Examples:

uv run maid dev watch --pack path/to/my-pack/
uv run maid dev watch --pack ./my-pack --port 5000 --include '*.py,*.json'

maid dev generate¶

Generate content using AI (rooms, items, NPCs).

uv run maid dev generate CONTENT_TYPE NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`CONTENT_TYPE`	str	Yes	Type of content to generate (room, item, npc)
`NAME`	str	Yes	Name for the generated content

Options:

Option	Type	Default	Description
`--output`, `-o`	path	—	Output file

maid dev playground¶

Start a sandbox server with builder access for interactive world prototyping.

uv run maid dev playground [OPTIONS]

Options:

Option	Type	Default	Description
`--port`, `-p`	int	`4000`	Telnet port
`--trace-events/--no-trace-events`	flag	trace-events	Log all EventBus events to console

Examples:

uv run maid dev playground
uv run maid dev playground --port 5000
uv run maid dev playground --no-trace-events

maid dev ai-player-report¶

Show AI player behavior report from a running server.

uv run maid dev ai-player-report [OPTIONS]

Options:

Option	Type	Default	Description
`--player`, `-p`	str	—	Specific player ID
`--violations`	flag	false	Show violations only
`--host`	str	`localhost`	Server host
`--port`	int	`8080`	Server port

Content Pack Commands¶

maid content list¶

List installed content packs.

uv run maid content list

This command takes no options. It discovers all installed content packs and displays their name, version, description, and dependencies.

maid content info¶

Show information about a content pack.

uv run maid content info PACK_NAME

maid content validate¶

Validate a content pack or content file.

uv run maid content validate PATH

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Path to content pack or JSON file

Database Commands¶

maid db init¶

Initialize the database with migration infrastructure.

uv run maid db init [OPTIONS]

Options:

Option	Type	Default	Description
`--force`, `-f`	flag	false	Force initialization

maid db migrate¶

Run pending database migrations.

uv run maid db migrate [OPTIONS]

Options:

Option	Type	Default	Description
`--target`	int	—	Target sequence number
`--namespace`	str	(all)	Namespace filter
`--dry-run`	flag	false	Show plan without executing
`--online-safe`	flag	false	Only run ONLINE_SAFE migrations
`--enabled-packs`	str	—	Comma-separated pack names
`--format`	str	`text`	Output format: `text` or `json`
`--backup`	flag	false	Request a safety backup reminder before executing

maid db rollback¶

Roll back migrations for a namespace.

uv run maid db rollback [OPTIONS]

Options:

Option	Type	Default	Description
`--namespace`	str	required	Namespace to roll back
`--steps`	int	`1`	Number of migrations to roll back
`--dry-run`	flag	false	Show plan without executing
`--force`	flag	false	Skip safety checks
`--format`	str	`text`	Output format: `text` or `json`

maid db status¶

Show migration status for all namespaces.

uv run maid db status [OPTIONS]

Options:

Option	Type	Default	Description
`--namespace`	str	(all)	Namespace filter
`--show-pending`	flag	false	Show pending count
`--show-checkpoints`	flag	false	Show in-progress checkpoints
`--format`	str	`text`	Output format: `text` or `json`

maid db history¶

Show migration history.

uv run maid db history [OPTIONS]

Options:

Option	Type	Default	Description
`--namespace`	str	(all)	Namespace filter
`--limit`	int	`20`	Maximum number of entries to show
`--include-rollbacks`	flag	false	Include rollback log entries
`--format`	str	`text`	Output format: `text` or `json`

maid db create¶

Generate a new migration file.

uv run maid db create DESCRIPTION [OPTIONS]

Arguments:

Argument	Type	Required	Description
`DESCRIPTION`	str	Yes	Migration description

Options:

Option	Type	Default	Description
`--namespace`	str	required	Migration namespace
`--template`	str	`ddl`	Template type: `jsonb`, `ddl`, or `seed`
`--collection`	str	—	Collection name for jsonb template
`--component`	str	—	Component name for jsonb template
`--field`	str	—	Field name for jsonb template

maid db validate¶

Validate migration integrity (checksum verification).

uv run maid db validate [OPTIONS]

Options:

Option	Type	Default	Description
`--fix-checksums`	flag	false	Fix mismatches
`--cleanup-checkpoints`	flag	false	Remove stale checkpoints
`--format`	str	`text`	Output format: `text` or `json`

maid db baseline¶

Mark existing schema as migrated to a given version.

uv run maid db baseline [OPTIONS]

Options:

Option	Type	Default	Description
`--namespace`	str	required	Namespace
`--at-version`	int	required	Version to baseline at
`--force`	flag	false	Overwrite existing records

maid db cleanup¶

Remove migration artifacts for a decommissioned pack.

uv run maid db cleanup [OPTIONS]

Options:

Option	Type	Default	Description
`--namespace`	str	required	Namespace to clean

maid db repair¶

Repair migration state.

uv run maid db repair [OPTIONS]

Options:

Option	Type	Default	Description
`--clear-pending`	flag	false	Clear stuck pending migrations
`--cleanup-checkpoints`	flag	false	Remove orphaned checkpoints
`--fix-checksums`	flag	false	Re-compute checksums

maid db backup¶

Backup the document store data to JSON.

uv run maid db backup [OPTIONS]

Options:

Option	Type	Default	Description
`--output`, `-o`	path	`backup.json`	Output file path
`--collection`, `-c`	str	(all)	Specific collection to backup

maid db restore¶

Restore data from a backup file.

uv run maid db restore INPUT_FILE [OPTIONS]

Arguments:

Argument	Type	Required	Description
`INPUT_FILE`	path	Yes	Backup file to restore

Options:

Option	Type	Default	Description
`--collection`, `-c`	str	(all)	Specific collection to restore
`--merge`, `-m`	flag	false	Merge with existing data instead of replacing

Data Commands¶

maid data init¶

Initialize a new content data directory with example YAML files.

uv run maid data init PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Directory to initialize with content data files

Options:

Option	Type	Default	Description
`--type`, `-t`	str	(all)	Create only a specific entity type template: `room`, `npc`, or `item`
`--all`, `-a`	flag	false	Create all entity type templates (default when `--type` is not specified)
`--force`, `-f`	flag	false	Overwrite existing files

maid data validate¶

Validate content data files against schemas and semantic rules.

uv run maid data validate [PATH] [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	No	Path to YAML file or directory to validate

Options:

Option	Type	Default	Description
`--strict/--lenient`	flag	strict	Validation strictness
`--skip-rule`	str	—	Rule IDs to skip
`--skip-rules`	str	—	Comma-separated rule IDs to skip
`--list-rules`, `-l`	flag	false	List semantic rules and exit

maid data lint¶

Lint content data files for style and formatting issues.

uv run maid data lint PATH

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Path to YAML file or directory to lint

maid data preview¶

Preview what loading would produce without applying changes.

uv run maid data preview PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Path to YAML file or directory to preview

Options:

Option	Type	Default	Description
`--strict/--lenient`	flag	strict	Validation strictness
`--skip-rule`	str	—	Rule IDs to skip

maid data load¶

Load content data into a fresh engine instance (offline).

uv run maid data load PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Path to YAML file or directory to load

Options:

Option	Type	Default	Description
`--reset`	flag	false	Reset existing instances
`--strict/--lenient`	flag	strict	Validation strictness
`--skip-rule`	str	—	Rule IDs to skip

maid data resolve¶

Resolve data references (e.g., @ref:room/bakery) in content files.

uv run maid data resolve PATH

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Path to YAML file or directory

maid data reload¶

Reload content data using a fresh engine instance (offline), replacing existing entities.

uv run maid data reload PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Path to YAML file or directory to reload

Options:

Option	Type	Default	Description
`--force`	flag	false	Skip confirmation prompt
`--skip-active`	flag	false	Skip entities in rooms with active players
`--strict/--lenient`	flag	strict	Validation strictness
`--skip-rule`	str	—	Rule IDs to skip

maid data unload¶

Unload a content pack's data from a fresh engine instance (offline).

uv run maid data unload PACK_NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PACK_NAME`	str	Yes	Content pack name to unload

Options:

Option	Type	Default	Description
`--force`	flag	false	Force unload without confirmation

maid data diff¶

Show differences between content data files.

uv run maid data diff PATH1 [PATH2]

Arguments:

Argument	Type	Required	Description
`PATH1`	path	Yes	First YAML file/directory (or sole target for single-arg mode)
`PATH2`	path	No	Second YAML file/directory

maid data migrate¶

Run content data schema migrations.

uv run maid data migrate [PATH] [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	No	Path to YAML file or directory

Options:

Option	Type	Default	Description
`--target-version`, `-t`	str	—	Target schema version (e.g., `v2`)
`--dry-run`, `-n`	flag	false	Show changes without modifying
`--backup`, `-b`	flag	false	Create `.bak` files before modifying
`--list`, `-l`	flag	false	List available migrations

maid data export¶

Export entities from the running engine to YAML files.

uv run maid data export OUTPUT_DIR [OPTIONS]

Arguments:

Argument	Type	Required	Description
`OUTPUT_DIR`	path	Yes	Directory to write exported YAML files

Options:

Option	Type	Default	Description
`--type`, `-t`	str	—	Export only this entity type (e.g., `room`, `npc`, `item`)
`--zone`, `-z`	str	—	Export only entities in this zone
`--pack`, `-p`	str	—	Export only entities from this content pack

maid data watch¶

Watch a directory for YAML file changes and auto-validate/reload.

uv run maid data watch PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Directory to watch for YAML file changes

Options:

Option	Type	Default	Description
`--validate/--no-validate`	flag	validate	Auto-validate on change
`--reload`	flag	false	Auto-reload into running server on change
`--debounce`	int	`500`	Debounce interval in milliseconds
`--strict/--lenient`	flag	strict	Validation strictness

maid data schema list¶

List all registered component schemas.

uv run maid data schema list

maid data schema show¶

Show details and fields for a specific component schema.

uv run maid data schema show COMPONENT_TYPE

Arguments:

Argument	Type	Required	Description
`COMPONENT_TYPE`	str	Yes	Component schema name

maid data schema export¶

Export component schemas to JSON Schema files.

uv run maid data schema export OUTPUT_DIR

Arguments:

Argument	Type	Required	Description
`OUTPUT_DIR`	path	Yes	Directory to write schema files to

maid data schema setup-ide¶

Configure IDE for YAML content authoring with schema validation.

uv run maid data schema setup-ide [OPTIONS]

Options:

Option	Type	Default	Description
`--schema-dir`	path	`schemas`	Directory containing (or to export) schema files
`--export/--no-export`	flag	export	Export schemas before configuring IDE

Environment Variables¶

The CLI respects the following environment variables:

Variable	Description
`MAID_DEBUG`	Enable debug mode (`true`/`false`)
`MAID_LOG_LEVEL`	Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`MAID_CONFIG_FILE`	Path to configuration file

Exit Codes¶

Code	Description
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	Configuration error
`4`	Permission denied
`64`	Engine denied an ops verb / auth tier mismatch
`69`	Service unavailable (ops socket missing/unreachable, used by `maid ops` verbs)
`77`	Permission denied at socket level (used by `maid ops` verbs)
`78`	Deferred implementation / config unusable (used by ops stubs)

Plugin Commands¶

The plugin command group provides tools for plugin development, quality checking, and registry management.

maid plugin new¶

Create a new MAID content pack plugin.

uv run maid plugin new [NAME] [OPTIONS]

Arguments:

Argument	Type	Required	Description
`NAME`	str	No	Plugin name (lowercase, hyphens allowed)

Options:

Option	Type	Default	Description
`--output`, `-o`	path	`.`	Output directory
`--template`, `-t`	str	`standard`	Template type: minimal, standard, full, system_only, command_only
`--description`, `-d`	str		Plugin description
`--author`, `-a`	str		Author name
`--email`, `-e`	str		Author email
`--license`, `-l`	str	`MIT`	License type
`--non-interactive`, `-n`	flag	false	Run without interactive wizard
`--git`, `-g`	flag	false	Initialize git repository

Template Types:

Template	Description
`minimal`	Just pack.py and pyproject.toml
`standard`	Recommended - includes tests, docs, CI
`full`	Everything including example files
`system_only`	Minimal + systems/ directory
`command_only`	Minimal + commands/ directory

Examples:

# Interactive wizard (recommended for new users)
uv run maid plugin new

# Non-interactive with name argument
uv run maid plugin new my-combat-system

# Full options for CI/scripting
uv run maid plugin new my-plugin --template full --author "John Doe" --non-interactive

# With git initialization
uv run maid plugin new my-plugin -o ./plugins -t minimal --git

maid plugin check¶

Run quality checks on a MAID plugin.

uv run maid plugin check PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Path to plugin directory

Options:

Option	Type	Default	Description
`--skip-tests`	flag	false	Skip running tests
`--skip-coverage`	flag	false	Skip coverage check
`--skip-linting`	flag	false	Skip linting check
`--skip-type-check`	flag	false	Skip type checking
`--coverage-threshold`, `-c`	int	80	Minimum coverage percentage
`--json`, `-j`	flag	false	Output as JSON
`--verbose`, `-v`	flag	false	Show detailed output

Quality Checks:

Manifest validation (pyproject.toml)
Protocol compliance (ContentPack interface)
Test existence and passing
Code coverage (>80% default)
Documentation (README.md sections)
Linting (ruff)
Type hints (mypy)
Version compatibility

Examples:

# Full quality check
uv run maid plugin check ./my-plugin

# Skip tests and coverage
uv run maid plugin check ./my-plugin --skip-tests --skip-coverage

# Custom coverage threshold
uv run maid plugin check ./my-plugin --coverage-threshold 90

# JSON output for CI
uv run maid plugin check ./my-plugin --json

maid plugin test¶

Test content packs for protocol compliance and basic functionality.

uv run maid plugin test [PATH] [OPTIONS]

Options:

Option	Type	Default	Description
`--compliance-only`, `-c`	flag	false	Run only protocol compliance tests
`--verbose`, `-v`	flag	false	Show detailed test output
`--lifecycle/--no-lifecycle`	flag	true	Run lifecycle tests
`--ticks`, `-t`	int	5	Number of ticks in lifecycle test

Examples:

# Test all discovered packs
uv run maid plugin test

# Quick compliance check only
uv run maid plugin test --compliance-only

# Verbose output with more ticks
uv run maid plugin test -v --ticks 20

maid plugin compliance¶

Check protocol compliance for content pack(s).

uv run maid plugin compliance [PACK_NAME] [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PACK_NAME`	str	No	Name of pack to check (all if omitted)

Options:

Option	Type	Default	Description
`--json`	flag	false	Output results as JSON

Examples:

# Check all packs
uv run maid plugin compliance

# Check specific pack
uv run maid plugin compliance maid-classic-rpg

# JSON output for CI/CD
uv run maid plugin compliance --json

maid plugin search¶

Search for plugins in the registry.

uv run maid plugin search QUERY [OPTIONS]

Arguments:

Argument	Type	Required	Description
`QUERY`	str	Yes	Search query string

Options:

Option	Type	Default	Description
`--category`, `-c`	str		Filter by category
`--page`, `-p`	int	1	Page number
`--per-page`, `-n`	int	20	Results per page
`--registry-url`	str		Custom registry URL
`--json`, `-j`	flag	false	Output as JSON

Categories:

gameplay - Gameplay mechanics
world - World building
utility - Utility functions
integration - External integrations
other - Other plugins

Examples:

# Search for combat-related plugins
uv run maid plugin search combat

# Filter by category
uv run maid plugin search "magic system" --category gameplay

# Paginated search
uv run maid plugin search crafting --page 2 --per-page 10

# JSON output
uv run maid plugin search inventory --json

maid plugin install¶

Install a plugin from the registry.

uv run maid plugin install NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`NAME`	str	Yes	Plugin package name

Options:

Option	Type	Default	Description
`--version`, `-v`	str		Specific version (default: latest)
`--upgrade`, `-U`	flag	false	Upgrade if already installed
`--registry-url`	str		Custom registry URL
`--json`, `-j`	flag	false	Output as JSON

Examples:

# Install latest version
uv run maid plugin install maid-combat-system

# Install specific version
uv run maid plugin install maid-combat-system --version 1.2.0

# Upgrade existing installation
uv run maid plugin install maid-combat-system --upgrade

# JSON output
uv run maid plugin install maid-combat-system --json

maid plugin uninstall¶

Uninstall an installed plugin.

uv run maid plugin uninstall NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`NAME`	str	Yes	Plugin package name

Options:

Option	Type	Default	Description
`--force`, `-f`	flag	false	Skip confirmation prompt
`--registry-url`	str		Custom registry URL
`--json`, `-j`	flag	false	Output as JSON

Examples:

# Uninstall with confirmation
uv run maid plugin uninstall maid-combat-system

# Uninstall without confirmation
uv run maid plugin uninstall maid-combat-system --force

maid plugin registry-list¶

List all installed plugins from the registry.

uv run maid plugin registry-list [OPTIONS]

Options:

Option	Type	Default	Description
`--registry-url`	str		Custom registry URL
`--json`, `-j`	flag	false	Output as JSON
`--verbose`, `-v`	flag	false	Show detailed information

Examples:

# List installed plugins
uv run maid plugin registry-list

# Detailed output
uv run maid plugin registry-list --verbose

# JSON output
uv run maid plugin registry-list --json

maid plugin registry-info¶

Show detailed plugin information from the registry.

uv run maid plugin registry-info NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`NAME`	str	Yes	Plugin package name

Options:

Option	Type	Default	Description
`--registry-url`	str		Custom registry URL
`--json`, `-j`	flag	false	Output as JSON

Examples:

# Get plugin info
uv run maid plugin registry-info maid-combat-system

# JSON output
uv run maid plugin registry-info maid-combat-system --json

maid plugin scaffold-test¶

Generate a test file template for a content pack.

uv run maid plugin scaffold-test PACK_NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PACK_NAME`	str	Yes	Name of content pack

Options:

Option	Type	Default	Description
`--output`, `-o`	path	`.`	Output directory

Examples:

# Generate test file in current directory
uv run maid plugin scaffold-test my-pack

# Generate in tests/ directory
uv run maid plugin scaffold-test my-pack -o tests/

maid plugin publish¶

Publish a local content pack to the registry index.

uv run maid plugin publish PACK_PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PACK_PATH`	str	Yes	Path to the content pack directory to publish

Options:

Option	Type	Default	Description
`--registry-url`	str	—	Custom registry URL
`--json`, `-j`	flag	false	Output as JSON

Examples:

uv run maid plugin publish packages/maid-classic-rpg
uv run maid plugin publish ./my-pack --json

Pack Commands¶

The pack command group provides content pack hot reload management for development.

maid pack list¶

List all loaded content packs.

uv run maid pack list [OPTIONS]

Options:

Option	Type	Default	Description
`--json`, `-j`	flag	false	Output as JSON
`--verbose`, `-v`	flag	false	Show detailed information

Examples:

# List discovered packs
uv run maid pack list

# Detailed output
uv run maid pack list --verbose

# JSON output
uv run maid pack list --json

maid pack reload¶

Reload a content pack at runtime.

uv run maid pack reload PACK_NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PACK_NAME`	str	Yes	Name of content pack to reload

Options:

Option	Type	Default	Description
`--preserve-state/--no-preserve-state`	flag	true	Preserve system state during reload
`--json`, `-j`	flag	false	Output as JSON

Note: Requires a running server with hot reload support. Start with maid server start --watch.

Examples:

# Reload a pack
uv run maid pack reload maid-classic-rpg

# Reload without preserving state
uv run maid pack reload my-pack --no-preserve-state

# JSON output
uv run maid pack reload my-pack --json

maid pack load¶

Load a content pack from a path.

uv run maid pack load PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Path to content pack directory

Options:

Option	Type	Default	Description
`--json`, `-j`	flag	false	Output as JSON

Note: The directory should contain manifest.toml and pack.py files.

Examples:

# Load pack from path
uv run maid pack load /path/to/my-pack

# JSON output
uv run maid pack load ./custom-content --json

maid pack unload¶

Unload a content pack from the running engine.

uv run maid pack unload PACK_NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PACK_NAME`	str	Yes	Name of content pack to unload

Options:

Option	Type	Default	Description
`--force`, `-f`	flag	false	Force unload even with dependencies
`--json`, `-j`	flag	false	Output as JSON

Examples:

# Unload a pack
uv run maid pack unload my-pack

# Force unload despite dependencies
uv run maid pack unload my-pack --force

maid pack watch¶

Watch a content pack for file changes and auto-reload.

uv run maid pack watch PACK_NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PACK_NAME`	str	Yes	Name of content pack to watch

Options:

Option	Type	Default	Description
`--path`, `-p`	path		Path to source directory (auto-detected)
`--debounce`, `-d`	float	0.5	Debounce delay in seconds
`--json`, `-j`	flag	false	Output as JSON

Note: Requires a running server. For easier development, use maid server start --watch.

Examples:

# Watch a pack (auto-detect path)
uv run maid pack watch maid-stdlib

# Watch with explicit path
uv run maid pack watch my-pack --path ./src/my_pack

# Custom debounce delay
uv run maid pack watch my-pack --debounce 1.0

maid pack status¶

Show detailed status of a content pack.

uv run maid pack status PACK_NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PACK_NAME`	str	Yes	Name of content pack

Options:

Option	Type	Default	Description
`--json`, `-j`	flag	false	Output as JSON

Examples:

# Show pack status
uv run maid pack status maid-classic-rpg

# JSON output
uv run maid pack status my-pack --json

maid pack history¶

Show hot reload history.

uv run maid pack history [OPTIONS]

Options:

Option	Type	Default	Description
`--limit`, `-n`	int	10	Number of recent operations to show
`--json`, `-j`	flag	false	Output as JSON

Note: Requires a running server.

Examples:

# Show recent reload history
uv run maid pack history

# Show last 20 operations
uv run maid pack history --limit 20

Login to the admin API and save authentication token.

uv run maid pack login [OPTIONS]

Options:

Option	Type	Default	Description
`--host`, `-H`	str	localhost	Server hostname
`--port`, `-p`	int	8080	Server port
`--json`, `-j`	flag	false	Output as JSON

The token is saved to ~/.maid/admin_token with secure permissions.

Environment Variables:

MAID_SERVER_HOST - Server hostname
MAID_SERVER_PORT - Server port
MAID_ADMIN_TOKEN - Admin JWT token (alternative to login)

Examples:

# Login to local server
uv run maid pack login

# Login to remote server
uv run maid pack login --host myserver.com --port 8080

maid pack logout¶

Logout and remove saved authentication token.

uv run maid pack logout [OPTIONS]

Options:

Option	Type	Default	Description
`--json`, `-j`	flag	false	Output as JSON

Examples:

uv run maid pack logout

Quickstart Commands¶

The quickstart command group scaffolds new MAID content pack projects.

maid quickstart new¶

Scaffold a new MAID content pack project.

uv run maid quickstart new NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`NAME`	str	Yes	Name of the new project (e.g., `my-cool-world`)

Options:

Option	Type	Default	Description
`--template`, `-t`	str	`standard`	Template level: `minimal`, `standard`, or `full`
`--author`, `-a`	str		Author name
`--email`, `-e`	str		Author email
`--description`, `-d`	str		One-line description
`--license`, `-l`	str	`MIT`	SPDX license identifier

Templates:

Template	Description
`minimal`	YAML-only content pack — no Python code at all. Auto-discovered by the engine.
`standard`	YAML data + Python `DataDrivenContentPack` subclass with systems, commands, events, and tests.
`full`	Everything from standard plus IDE config (`.vscode/`), CI (`.github/workflows/`), multi-zone world, and a `docs/` directory.

Examples:

# Scaffold with the default "standard" template
uv run maid quickstart new my-world

# Create a YAML-only content pack (no Python)
uv run maid quickstart new my-world --template minimal

# Create a full project with author metadata
uv run maid quickstart new my-rpg --template full --author "Jane Doe"

# Specify description and license
uv run maid quickstart new my-pack -d "A spooky dungeon pack" -l "Apache-2.0"

Generated Structure (standard template):

my-world/
├── manifest.toml
├── pyproject.toml
├── README.md
├── src/my_world/
│   ├── __init__.py
│   ├── pack.py
│   ├── data/
│   │   ├── rooms.yaml
│   │   ├── items.yaml
│   │   └── npcs.yaml
│   ├── systems/
│   ├── commands/
│   └── events/
└── tests/
    └── test_pack.py

Next Steps (after scaffolding):

cd my-world
uv sync            # Install dependencies (standard/full only)
uv run pytest tests/
uv run maid server start

Batch Commands¶

The batch command group provides batch file processing capabilities.

maid batch run¶

Execute a batch file.

uv run maid batch run FILE_PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`FILE_PATH`	path	Yes	Path to batch file

Options:

Option	Type	Default	Description
`--type`, `-t`	str	`auto`	Batch type: auto, command, code, mixed
`--dry-run`, `-n`	flag	false	Parse and validate without executing
`--continue-on-error`, `-c`	flag	false	Continue execution after errors
`--timeout`	float	300.0	Execution timeout in seconds
`--verbose`, `-v`	flag	false	Show detailed output

Batch Types:

Type	Description
`auto`	Auto-detect from file extension and content
`command`	Game commands (one per line)
`code`	Python code with engine/world access
`mixed`	Commands and code blocks (#BEGIN CODE / #END CODE)

Examples:

# Execute batch file
uv run maid batch run setup.batch

# Execute as Python code
uv run maid batch run world_setup.py --type=code

# Dry run (validate only)
uv run maid batch run migration.batch --dry-run

# Continue on errors
uv run maid batch run content.batch --continue-on-error

maid batch validate¶

Validate a batch file without executing.

uv run maid batch validate FILE_PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`FILE_PATH`	path	Yes	Path to batch file

Options:

Option	Type	Default	Description
`--type`, `-t`	str	`auto`	Batch type: auto, command, code, mixed

Examples:

# Validate batch file
uv run maid batch validate setup.batch

# Validate Python script
uv run maid batch validate script.py --type=code

maid batch info¶

Show information about a batch file.

uv run maid batch info FILE_PATH

Examples:

uv run maid batch info setup.batch

Documentation Commands¶

The docs command group provides documentation generation and serving.

maid docs serve¶

Serve documentation locally for development with live reload support.

uv run maid docs serve [OPTIONS]

Options:

Option	Type	Default	Description
`--port`, `-p`	int	`8000`	Port to serve documentation on
`--host`, `-h`	str	`127.0.0.1`	Host to bind to
`--open`, `-o`	flag	false	Open documentation in browser

Examples:

uv run maid docs serve
uv run maid docs serve --port 9000
uv run maid docs serve --open

maid docs build¶

Build documentation for deployment as static HTML.

uv run maid docs build [OPTIONS]

Options:

Option	Type	Default	Description
`--output`, `-o`	str	`site`	Output directory for built documentation
`--clean/--no-clean`	flag	clean	Clean output directory before building
`--strict`, `-s`	flag	false	Enable strict mode (fail on warnings)

Examples:

uv run maid docs build
uv run maid docs build --output docs-build
uv run maid docs build --strict

World Commands¶

The world command group provides world visualization and export.

maid world map¶

Export the game world as a visual map.

uv run maid world map DATA_PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`DATA_PATH`	path	Yes	Path to room data (directory of JSON files or YAML area file)

Options:

Option	Type	Default	Description
`--format`, `-f`	str	`dot`	Output format: dot, ascii, svg, or html
`--output`, `-o`	path	—	Output file path (defaults to stdout for dot/ascii)

Examples:

uv run maid world map data/rooms --format dot
uv run maid world map data/millbrook_town.yaml --format ascii
uv run maid world map data/rooms -f svg -o map.svg
uv run maid world map data/rooms -f html -o map.html

AI Commands¶

The ai command group provides AI-powered content generation commands.

maid ai generate¶

Generate pipeline-compatible content from a description.

uv run maid ai generate CONTENT_TYPE NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`CONTENT_TYPE`	str	Yes	Content type: room, npc, item, monster, quest, lore, area, dungeon
`NAME`	str	Yes	Name/title for the generated content

Options:

Option	Type	Default	Description
`--output`, `-o`	path	—	Output file path (default: stdout)
`--provider`, `-p`	str	—	LLM provider name
`--model`, `-m`	str	—	Model override
`--temperature`	float	—	Temperature (0.0-2.0)
`--style`	str	epic	Style preset: epic, gritty, whimsical, horror, pastoral
`--zone`	str	—	Zone name for room assignment
`--level-range`	str	—	Level range, e.g. '5-10'
`--tags`	str	—	Comma-separated tags
`--theme`	str	—	Thematic guidance
`--context`	path	—	Additional context file(s) (repeatable)
`--world-context/--no-world-context`	flag	true	Inject existing world state
`--few-shot/--no-few-shot`	flag	true	Include few-shot examples
`--validate/--no-validate`	flag	true	Run validation on output
`--interactive/--no-interactive`	flag	false	Interactive review mode
`--max-tokens`	int	—	Max response tokens
`--retries`	int	2	Max retry attempts
`--seed`	int	—	Random seed for reproducibility
`--dry-run`	flag	false	Show prompt without sending
`--format`	str	yaml	Output format: yaml or json
`--pack`	str	—	Content pack context

maid ai schema¶

Show the expected schema for a content type.

uv run maid ai schema CONTENT_TYPE

Arguments:

Argument	Type	Required	Description
`CONTENT_TYPE`	str	Yes	Content type to show schema for

maid ai estimate¶

Estimate generation cost without calling the LLM.

uv run maid ai estimate CONTENT_TYPE NAME [OPTIONS]

Arguments:

Argument	Type	Required	Description
`CONTENT_TYPE`	str	Yes	Content type to estimate
`NAME`	str	Yes	Name/title for the content

Options:

Option	Type	Default	Description
`--style`	str	epic	Style preset
`--provider`, `-p`	str	—	LLM provider name
`--model`, `-m`	str	—	Model override
`--max-tokens`	int	1024	Assumed completion token budget

maid ai validate-output¶

Validate AI-generated YAML against content schemas.

uv run maid ai validate-output PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	YAML file to validate

Options:

Option	Type	Default	Description
`--type`, `-t`	str	—	Content type (inferred from filename or top-level key if omitted)

maid ai cache¶

Manage the AI response cache.

uv run maid ai cache ACTION [OPTIONS]

Arguments:

Argument	Type	Required	Description
`ACTION`	str	Yes	Action: stats, clear

Options:

Option	Type	Default	Description
`--cache-dir`	path	`~/.maid/ai-cache`	Cache directory

maid ai describe¶

Generate or improve descriptions for existing entities.

uv run maid ai describe ENTITY_PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`ENTITY_PATH`	path	Yes	Path to entity YAML file

Options:

Option	Type	Default	Description
`--output`, `-o`	path	—	Output file (defaults to stdout / overwrites input)
`--provider`, `-p`	str	—	LLM provider name
`--style`	str	epic	Style preset
`--improve`	flag	false	Improve existing description rather than replace
`--write/--no-write`	flag	false	Write changes back to the input file

maid ai review¶

AI-powered content review.

uv run maid ai review PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	Path to YAML file or directory

Options:

Option	Type	Default	Description
`--provider`, `-p`	str	—	LLM provider name
`--focus`	str	all	Review focus: quality, balance, consistency, all
`--output`, `-o`	path	—	Optional report output (YAML)

maid ai populate¶

Add NPCs/items to an existing area, generating a multi-doc YAML.

uv run maid ai populate AREA_PATH [OPTIONS]

Arguments:

Argument	Type	Required	Description
`AREA_PATH`	path	Yes	Path to existing area YAML file

Options:

Option	Type	Default	Description
`--npcs`	int	2	Number of NPCs to add
`--items`	int	2	Number of items to add
`--style`, `-s`	str	epic	Style preset
`--provider`, `-p`	str	—	Provider (defaults to mock)
`--output`, `-o`	path	—	Optional output path (defaults to stdout)
`--validate/--no-validate`	flag	true	Run validation on generated entities

maid ai connect¶

Create connections between two areas (emits an exits patch as YAML).

uv run maid ai connect AREA1 AREA2 [OPTIONS]

Arguments:

Argument	Type	Required	Description
`AREA1`	str	Yes	First area name or room id
`AREA2`	str	Yes	Second area name or room id

Options:

Option	Type	Default	Description
`--direction`, `-d`	str	east	Direction from area1 to area2
`--bidirectional/--one-way`	flag	true	Create reverse exit too
`--output`, `-o`	path	—	Optional output path

maid ai balance¶

Analyze content balance: counts and level distribution.

uv run maid ai balance PATH

Arguments:

Argument	Type	Required	Description
`PATH`	path	Yes	YAML file or directory to analyze

Internationalization Commands¶

The i18n command group provides internationalization utilities.

maid i18n extract¶

Extract translatable strings from Python source files.

uv run maid i18n extract [PATHS]... [OPTIONS]

Arguments:

Argument	Type	Required	Description
`PATHS`	path	No	Paths to scan for translatable strings (files or directories)

Options:

Option	Type	Default	Description
`--output`, `-o`	path	`messages.pot`	Output POT file path
`--project`, `-p`	str	`MAID`	Project name for POT header
`--version`, `-v`	str	`1.0.0`	Project version for POT header
`--exclude`, `-x`	str	—	Patterns to exclude (can be repeated)

Examples:

uv run maid i18n extract packages/ --output=locales/messages.pot
uv run maid i18n extract src/ --exclude="**/tests/*"

maid i18n init¶

Initialize a new locale from the POT template.

uv run maid i18n init LOCALE [OPTIONS]

Arguments:

Argument	Type	Required	Description
`LOCALE`	str	Yes	Locale code (e.g., `es`, `de`, `fr`)

Options:

Option	Type	Default	Description
`--pot`, `-p`	path	`messages.pot`	POT template file
`--output-dir`, `-o`	path	`locales`	Output directory for locale files
`--force`, `-f`	flag	false	Overwrite existing PO file

Examples:

uv run maid i18n init es
uv run maid i18n init de --pot=locales/messages.pot --output-dir=locales/

maid i18n update¶

Update PO files with new messages from POT template.

uv run maid i18n update [LOCALE] [OPTIONS]

Arguments:

Argument	Type	Required	Description
`LOCALE`	str	No	Locale to update (or `all` for all locales)

Options:

Option	Type	Default	Description
`--pot`, `-p`	path	`messages.pot`	POT template file
`--locale-dir`, `-l`	path	`locales`	Locale directory
`--backup/--no-backup`	flag	backup	Create backup of existing PO files

maid i18n compile¶

Compile PO files to binary MO format.

uv run maid i18n compile [LOCALE] [OPTIONS]

Arguments:

Argument	Type	Required	Description
`LOCALE`	str	No	Locale to compile (or `all` for all locales)

Options:

Option	Type	Default	Description
`--locale-dir`, `-l`	path	`locales`	Locale directory
`--output-dir`, `-o`	path	—	Output directory for MO files (defaults to same as PO)

maid i18n check¶

Check translation status and report missing/fuzzy translations.

uv run maid i18n check [LOCALE] [OPTIONS]

Arguments:

Argument	Type	Required	Description
`LOCALE`	str	No	Locale to check (or `all` for all locales)

Options:

Option	Type	Default	Description
`--locale-dir`, `-l`	path	`locales`	Locale directory
`--show-missing/--hide-missing`	flag	show-missing	Show missing translations
`--show-fuzzy/--hide-fuzzy`	flag	show-fuzzy	Show fuzzy translations
`--verbose`, `-v`	flag	false	Show detailed information

maid i18n coverage¶

Check translation coverage and enforce minimum threshold.

uv run maid i18n coverage [OPTIONS]

Options:

Option	Type	Default	Description
`--pot`, `-p`	path	`messages.pot`	POT template file (master messages)
`--locale-dir`, `-l`	path	`locales`	Locale directory
`--threshold`, `-t`	float	`80.0`	Minimum coverage percentage required (0–100)
`--locale`	str	—	Specific locales to check (can be repeated, default: all)
`--strict`, `-s`	flag	false	Exit with error if any locale is below threshold
`--json`	flag	false	Output as JSON for CI integration

Examples:

uv run maid i18n coverage --threshold=80 --strict
uv run maid i18n coverage --locale=es --locale=de --threshold=90
uv run maid i18n coverage --json

maid i18n list¶

List available locales.

uv run maid i18n list [OPTIONS]

Options:

Option	Type	Default	Description
`--locale-dir`, `-l`	path	`locales`	Locale directory

Status Commands¶

maid status¶

Show the engine's deploy-contract identity and liveness state.

Probes the ops UDS for a live engine. When the engine is online, exits 0 with state: "online" plus the structured engine status payload. When the engine is offline (socket missing, refused, or unreachable) exits with code 3.

uv run maid status [OPTIONS]

Options:

Option	Type	Default	Description
`--json`	flag	false	Emit machine-readable JSON instead of human-friendly text

Exit codes: 0 = online, 3 = offline (socket unreachable).

Examples:

# Check if engine is running (human-readable)
uv run maid status

# Machine-readable check (for monitoring scripts)
uv run maid status --json

maid status render-html¶

Write a self-contained static HTML status page to a file.

Probes the ops UDS, then renders a single-file HTML dashboard (no external assets) suitable for nginx / /var/www static serving. Always exits 0 once the file is written; the page itself communicates online/offline via a coloured badge.

uv run maid status render-html --output PATH

Options:

Option	Type	Required	Description
`--output`, `-o`	path	Yes	File path to write the rendered HTML status page to

Examples:

uv run maid status render-html --output /var/www/status.html

Ops Commands¶

Operator control-plane verbs for managing a live MAID instance. Verbs communicate with the engine via the ops UDS (Unix Domain Socket). Most verbs require membership in maid-ops-ro or a higher tier.

Note: status, delete-player-data, audit-log, generate-secret, list-secrets, rotate-secret, and the top-level kill-switch verbs are implemented. Several UDS-backed control-plane verbs remain preview/stub commands until their engine-side handlers land; stubs exit with code 78 (EX_CONFIG).

maid ops status¶

Show live operational status (uptime, tick rate, session count, etc.).

uv run maid ops status [OPTIONS]

Options:

Option	Type	Default	Description
`--instance`, `-i`	str	from env	Instance name
`--socket`	str	derived from instance	Override UDS path
`--json`	flag	false	Emit machine-readable JSON

Exit codes: 0 = success, 64 = engine denied the verb/auth tier mismatch, 69 = socket unavailable, 77 = permission denied, 78 = config error.

Ops verb status¶

Implemented local/operator helpers:

delete-player-data — GDPR erasure helper.
audit-log — audit log inspection subcommands.
generate-secret, list-secrets, rotate-secret — local secret management helpers.
kill-switch trip|reset|status — top-level AI kill-switch verbs.

The following UDS/control-plane verbs are registered and accept documented arguments, but may exit 78 until their backing engine handlers land:

Verb	Description	Milestone
`doctor`	Run health/readiness checks	M9
`broadcast`	Send message to all sessions	M9
`announce`	Multi-channel announcement with severity/ETA	M9
`maintenance`	Schedule/cancel maintenance window	M9
`flush`	Flush persistence buffers	M9
`drain`	Drain sessions (graceful disconnect)	M9
`drain-shutdown`	Drain then shut down	M9
`reload-config`	Reload engine settings	M9
`pause-tick`	Pause tick loop	M9
`resume-tick`	Resume tick loop	M9
`backup`	Trigger backup	M9
`restore`	Restore from backup	M9
`hot-reload`	Trigger hot reload	M9

Environment Variables¶

The CLI respects the following environment variables:

Variable	Description
`MAID_DEBUG`	Enable debug mode (`true`/`false`)
`MAID_LOG_LEVEL`	Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`MAID_CONFIG_FILE`	Path to configuration file
`MAID_SERVER_HOST`	Server hostname for pack commands
`MAID_SERVER_PORT`	Server port for pack commands
`MAID_ADMIN_TOKEN`	Admin JWT token for pack commands

Exit Codes¶

Code	Description
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	Offline / configuration error (`maid status` when ops socket is unreachable)
`4`	Permission denied
`64`	Engine denied an ops verb / auth tier mismatch
`69`	Service unavailable (ops socket missing/unreachable, used by `maid ops` verbs)
`77`	Permission denied at socket level (used by `maid ops` verbs)
`78`	Deferred implementation / config unusable (used by ops stubs)

REST API Documentation - Using the generated API keys
SSL Configuration - Secure server setup
Admin API Reference - Programmatic key management
Hot Reload Guide - Using hot reload during development