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 operations
`content`	Content pack management
`dev`	Development tools
`api`	API key management
`plugin`	Plugin development, quality, and registry commands
`pack`	Content pack hot reload management
`batch`	Batch processing commands
`i18n`	Internationalization commands
`docs`	Documentation generation commands

Server Commands¶

maid server start¶

Start the MAID server.

uv run maid server start [OPTIONS]

Options:

Option	Type	Default	Description
`--host`	str	`0.0.0.0`	Host to bind to
`--telnet-port`	int	`4000`	Telnet port
`--web-port`	int	`8080`	Web/API port
`--debug`	flag	false	Enable debug mode

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
uv run maid server start --debug

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	Yes	Comma-separated permissions
`--expires-in-days`, `-e`	int	No	Days until key expires (omit for never)
`--rate-limit`, `-r`	int	No	Requests per minute (default: 60)

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-in-days 30

# 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
`--include-inactive`, `-i`	flag	false	Include revoked keys
`--format`, `-f`	str	`table`	Output format: table, json, csv

Examples:

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

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

# Output as JSON
uv run maid api list-keys --format 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
`--force`, `-f`	flag	false	Skip confirmation prompt

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

Arguments:

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

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:

engine - The GameEngine instance
world - The World instance
settings - Current settings

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	`anthropic`	AI provider to test
`--model`, `-m`	str	(provider default)	Model to use
`--max-tokens`	int	500	Maximum response tokens

Examples:

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

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

Content Pack Commands¶

maid content list¶

List available content packs.

uv run maid content list [OPTIONS]

Options:

Option	Type	Default	Description
`--loaded-only`	flag	false	Only show loaded packs

maid content info¶

Show information about a content pack.

uv run maid content info PACK_NAME

Database Commands¶

maid db migrate¶

Run database migrations.

uv run maid db migrate [OPTIONS]

Options:

Option	Type	Default	Description
`--revision`	str	`head`	Target revision

maid db rollback¶

Rollback database migrations.

uv run maid db rollback [OPTIONS]

Options:

Option	Type	Default	Description
`--revision`	str	`-1`	Target revision or steps back

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

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/

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

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

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`	Configuration error
`4`	Permission denied

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

CLI Reference¶

Overview¶

Command Groups¶

Server Commands¶

maid server start¶

API Key Commands¶

maid api generate-key¶

maid api list-keys¶

maid api revoke-key¶

maid api info¶

Development Commands¶

maid dev shell¶

maid dev test-ai¶

Content Pack Commands¶

maid content list¶

maid content info¶

Database Commands¶

maid db migrate¶

maid db rollback¶

Environment Variables¶

Exit Codes¶

Plugin Commands¶

maid plugin new¶

maid plugin check¶

maid plugin test¶

maid plugin compliance¶

maid plugin search¶

maid plugin install¶

maid plugin uninstall¶

maid plugin registry-list¶

maid plugin registry-info¶

maid plugin scaffold-test¶

Pack Commands¶

maid pack list¶

maid pack reload¶

maid pack load¶

maid pack unload¶

maid pack watch¶

maid pack status¶

maid pack history¶

maid pack login¶

maid pack logout¶

Batch Commands¶

maid batch run¶

maid batch validate¶

maid batch info¶

Environment Variables¶

Exit Codes¶

Related Documentation¶