CLI Reference¶

MAID provides a comprehensive command-line interface for server management, development, and content pack operations.

Global Options¶

maid --help     # Show help
maid --version  # Show version

Server Commands¶

maid server start¶

Start the MAID server.

maid server start [OPTIONS]

Options:

Option	Default	Description
`--config, -c`	None	Path to configuration file
`--host, -h`	0.0.0.0	Host to bind to
`--telnet-port, -t`	4000	Telnet port
`--web-port, -w`	8080	Web/WebSocket port
`--debug, -d`	False	Enable debug mode
`--watch`	False	Enable file watching for hot reload
`--watch-debounce`	0.5	Debounce delay for file watching (seconds)
`--content`	None	Content packs to load (repeatable)

Examples:

# Start with defaults
maid server start

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

# Custom ports
maid server start --telnet-port 5000 --web-port 9000

# Load specific content packs
maid server start --content maid-stdlib --content my-game

maid server status¶

Show server status.

maid server status

maid server stop¶

Stop the running server.

maid server stop

Database Commands¶

maid db init¶

Initialize the database.

maid db init [OPTIONS]

Options:

Option	Description
`--force, -f`	Force initialization (drop existing)

maid db migrate¶

Run database migrations.

maid db migrate [REVISION]

Arguments:

Argument	Default	Description
`REVISION`	head	Target revision

maid db backup¶

Backup database to JSON.

maid db backup [OPTIONS]

Options:

Option	Default	Description
`--output, -o`	backup.json	Output file path
`--collection, -c`	None	Specific collection to backup

Examples:

# Backup everything
maid db backup

# Backup specific collection
maid db backup --collection players --output players.json

maid db restore¶

Restore database from backup.

maid db restore INPUT_FILE [OPTIONS]

Arguments:

Argument	Description
`INPUT_FILE`	Backup file to restore

Options:

Option	Default	Description
`--collection, -c`	None	Specific collection to restore
`--merge, -m`	False	Merge with existing data

Examples:

# Full restore
maid db restore backup.json

# Restore single collection, merge with existing
maid db restore backup.json --collection players --merge

Content Pack Commands¶

maid content list¶

List installed content packs.

maid content list

Output:

Installed Content Packs
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Name             ┃ Version ┃ Description      ┃ Dependencies┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ maid-stdlib      │ 1.0.0   │ Standard library │ -           │
│ maid-classic-rpg │ 1.0.0   │ Classic RPG game │ maid-stdlib │
└──────────────────┴─────────┴──────────────────┴─────────────┘

maid content info¶

Show content pack details.

maid content info NAME

Arguments:

Argument	Description
`NAME`	Content pack name

maid content validate¶

Validate a content pack or file.

maid content validate PATH

Arguments:

Argument	Description
`PATH`	Path to content pack directory or JSON file

Plugin Commands¶

maid plugin new¶

Create a new content pack plugin.

maid plugin new [NAME] [OPTIONS]

Arguments:

Argument	Description
`NAME`	Plugin name (optional in interactive mode)

Options:

Option	Default	Description
`--output, -o`	.	Output directory
`--template, -t`	standard	Template: minimal, standard, full
`--description, -d`	None	Plugin description
`--author, -a`	None	Author name
`--email, -e`	None	Author email
`--license, -l`	MIT	License type
`--non-interactive, -n`	False	Non-interactive mode
`--git, -g`	False	Initialize git repository

Examples:

# Interactive wizard
maid plugin new

# Non-interactive
maid plugin new my-combat-system --non-interactive

# Full options
maid plugin new my-plugin \
  --template full \
  --author "John Doe" \
  --description "Combat system" \
  --git

maid plugin check¶

Run quality checks on a plugin.

maid plugin check PATH [OPTIONS]

Arguments:

Argument	Description
`PATH`	Path to plugin directory

Options:

Option	Default	Description
`--skip-tests`	False	Skip running tests
`--skip-coverage`	False	Skip coverage check
`--skip-linting`	False	Skip linting
`--skip-type-check`	False	Skip type checking
`--coverage-threshold, -c`	80	Minimum coverage %
`--json, -j`	False	Output as JSON
`--verbose, -v`	False	Verbose output

Examples:

# Full check
maid plugin check ./my-plugin

# Quick check (no tests)
maid plugin check ./my-plugin --skip-tests --skip-coverage

# CI-friendly JSON output
maid plugin check ./my-plugin --json

maid plugin test¶

Test a content pack.

maid plugin test [PATH] [OPTIONS]

Options:

Option	Default	Description
`--compliance-only, -c`	False	Only run protocol compliance tests
`--verbose, -v`	False	Verbose output
`--lifecycle/--no-lifecycle`	True	Run lifecycle tests
`--ticks, -t`	5	Number of ticks in lifecycle test

maid plugin compliance¶

Check protocol compliance.

maid plugin compliance [PACK_NAME] [OPTIONS]

Arguments:

Argument	Description
`PACK_NAME`	Pack name (or all if not specified)

Options:

Option	Default	Description
`--json`	False	Output as JSON

maid plugin scaffold-test¶

Generate a test file template.

maid plugin scaffold-test PACK_NAME [OPTIONS]

Arguments:

Argument	Description
`PACK_NAME`	Content pack name

Options:

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

Pack Hot Reload Commands¶

maid pack reload¶

Reload a content pack.

maid pack reload PACK_NAME [OPTIONS]

Options:

Option	Description
`--force`	Force reload even if unchanged

maid pack status¶

Show hot reload status.

maid pack status

Development Commands¶

maid dev shell¶

Start an interactive Python shell.

maid dev shell

Provides access to:

maid_engine module
get_settings() function
Entity, World classes
discover_content_packs() function

maid dev test-ai¶

Test AI provider.

maid dev test-ai PROMPT [OPTIONS]

Arguments:

Argument	Description
`PROMPT`	Prompt to send to AI

Options:

Option	Default	Description
`--provider, -p`	None	AI provider (default from config)

Examples:

maid dev test-ai "Tell me a joke"
maid dev test-ai "Hello" --provider openai

maid dev profile¶

Run profiling.

maid dev profile [OPTIONS]

Options:

Option	Default	Description
`--types, -t`	memory,tick	Profile types (comma-separated)
`--duration, -d`	60	Duration in seconds
`--output, -o`	None	Output file (.html, .json, .txt)
`--json`	False	JSON output to stdout

Profile Types:

memory - Memory allocations
tick - Tick performance
query - Database queries
network - Network I/O
all - All types

Examples:

# Profile for 30 seconds
maid dev profile --types=memory,tick --duration=30

# Save HTML report
maid dev profile -t all -d 60 -o report.html

maid dev memory-snapshot¶

Take a memory snapshot.

maid dev memory-snapshot [OPTIONS]

Options:

Option	Default	Description
`--output, -o`	None	Output file
`--depth`	10	Stack trace depth
`--top, -n`	20	Number of top allocations

maid dev reload¶

Hot reload modules, packs, or systems.

maid dev reload TARGET [OPTIONS]

Arguments:

Argument	Description
`TARGET`	Module, pack, or system name

Options:

Option	Default	Description
`--type, -t`	module	Type: module, pack, system
`--cascade/--no-cascade`	True	Cascade to dependents
`--watch, -w`	False	Watch mode
`--watch-path, -p`	None	Paths to watch (repeatable)
`--debounce, -d`	0.5	Debounce delay (seconds)

Examples:

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

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

# Watch mode
maid dev reload maid_engine --watch --watch-path src/

maid dev reload-status¶

Show reload manager status.

maid dev reload-status

maid dev generate¶

Generate content using AI.

maid dev generate TYPE NAME [OPTIONS]

Arguments:

Argument	Description
`TYPE`	Content type: room, item, npc
`NAME`	Name for the generated content

Options:

Option	Default	Description
`--output, -o`	None	Output file

Examples:

maid dev generate room "Dark Cave"
maid dev generate item "Ancient Sword" --output sword.json
maid dev generate npc "Mysterious Merchant"

maid dev info¶

Show MAID version and configuration.

maid dev info

Batch Commands¶

maid batch run¶

Execute a batch file.

maid batch run FILE [OPTIONS]

Arguments:

Argument	Description
`FILE`	Path to batch file

Options:

Option	Default	Description
`--type, -t`	auto	Type: auto, command, code, mixed
`--dry-run, -n`	False	Validate without executing
`--continue-on-error, -c`	False	Continue after errors
`--timeout`	300	Timeout in seconds
`--verbose, -v`	False	Verbose output

Examples:

# Run batch file
maid batch run setup.batch

# Dry run
maid batch run migration.batch --dry-run

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

maid batch validate¶

Validate a batch file.

maid batch validate FILE [OPTIONS]

Options:

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

maid batch info¶

Show batch file information.

maid batch info FILE

i18n Commands¶

maid i18n extract¶

Extract translatable strings.

maid i18n extract [OPTIONS]

maid i18n compile¶

Compile translations.

maid i18n compile [OPTIONS]

API Key Commands¶

maid api create¶

Create an API key.

maid api create [OPTIONS]

maid api list¶

List API keys.

maid api list

maid api revoke¶

Revoke an API key.

maid api revoke KEY_ID

Documentation Commands¶

maid docs serve¶

Serve documentation locally.

maid docs serve [OPTIONS]

maid docs build¶

Build documentation.

maid docs build [OPTIONS]

Root Commands¶

maid version¶

Show MAID version.

maid version

Environment Variables¶

All configuration can be set via environment variables with the MAID_ prefix:

# Server
MAID_TELNET__PORT=4000
MAID_WEB__PORT=8080

# Database
MAID_DB__HOST=localhost
MAID_DB__PORT=5432
MAID_DB__NAME=maid
MAID_DB__USER=maid
MAID_DB__PASSWORD=secret

# AI
MAID_AI__DEFAULT_PROVIDER=anthropic
MAID_AI__ANTHROPIC_API_KEY=sk-ant-...
MAID_AI__OPENAI_API_KEY=sk-...

# Game
MAID_GAME__TICK_RATE=4.0
MAID_DEBUG=true
MAID_LOG_LEVEL=DEBUG

Exit Codes¶

Code	Meaning
0	Success
1	General error
2	Command not found
3	Invalid arguments
4	Configuration error
5	Runtime error

CLI Reference¶

Global Options¶

Server Commands¶

maid server start¶

maid server status¶

maid server stop¶

Database Commands¶

maid db init¶

maid db migrate¶

maid db backup¶

maid db restore¶

Content Pack Commands¶

maid content list¶

maid content info¶

maid content validate¶

Plugin Commands¶

maid plugin new¶

maid plugin check¶

maid plugin test¶

maid plugin compliance¶

maid plugin scaffold-test¶

Pack Hot Reload Commands¶

maid pack reload¶

maid pack status¶

Development Commands¶

maid dev shell¶

maid dev test-ai¶

maid dev profile¶

maid dev memory-snapshot¶

maid dev reload¶

maid dev reload-status¶

maid dev generate¶

maid dev info¶

Batch Commands¶

maid batch run¶

maid batch validate¶

maid batch info¶

i18n Commands¶

maid i18n extract¶

maid i18n compile¶

API Key Commands¶

maid api create¶

maid api list¶

maid api revoke¶

Documentation Commands¶

maid docs serve¶

maid docs build¶

Root Commands¶

maid version¶

Environment Variables¶

Exit Codes¶

See Also¶