The MoFA CLI is a powerful command-line tool for creating, managing, and deploying AI agents. It provides a complete set of commands for project scaffolding, agent lifecycle management, configuration, and more.
Installation Install from crates.io
Install from source
Development installation
Verify Installation Quick Start # Create a new agent project mofa new my-agent cd my-agent # Set up your API key export OPENAI_API_KEY = "sk-..." # Run the agent cargo run
Command Structure The MoFA CLI follows a hierarchical command structure:
mofa [GLOBAL_FLAGS] <COMMAND> [SUBCOMMAND] [OPTIONS] [ARGS]
Global Flags Flag Description Default -v, --verboseEnable verbose output false--output-format <FORMAT>Output format (text, json, table) text-c, --config <PATH>Configuration file path - --tuiLaunch Terminal UI mode false-h, --helpPrint help information - -V, --versionPrint version information -
Available Commands
mofa new Create a new agent project from templates
mofa agent Manage agent lifecycle (start, stop, list, status)
mofa plugin Install and manage plugins
mofa session View and manage agent sessions
mofa config Manage global configuration
mofa db Database initialization and migrations
Terminal UI Mode Launch the interactive Terminal User Interface:
# Launch TUI mofa --tui # Or simply run without arguments mofa
The TUI provides:
Interactive agent management
Real-time status monitoring
Session browsing
Plugin discovery
Environment Variables OpenAI Configuration export OPENAI_API_KEY = "sk-your-api-key-here" export OPENAI_BASE_URL = "https://api.openai.com/v1" # Optional export OPENAI_MODEL = "gpt-4o" # Optional, default: gpt-4o
MoFA Configuration export MOFA_CONFIG_DIR = "~/.config/mofa" # Configuration directory export MOFA_DATA_DIR = "~/.local/share/mofa" # Data storage directory export RUST_LOG = "info,mofa=debug" # Logging level
Configuration Files The CLI looks for configuration files in the following locations (in order):
Path specified by --config flag
./agent.yml (current directory)./agent.yaml./agent.toml./agent.json~/.config/mofa/config.yml
YAML : .yml, .yaml (recommended)TOML : .tomlJSON : .json, .json5INI : .iniRON : .ron
Exit Codes Code Description 0Success 1General error 2Configuration error 3Agent not found 4Agent already running 5Database connection error 101Network error
Shell Completion Generate shell completion scripts:
mofa completions bash > ~/.local/share/bash-completion/completions/mofa
Shell completion generation requires building with the clap_complete feature.
Most commands support multiple output formats:
Text Format (Default) → Listing agents ┌────────────┬─────────────┬─────────┬────────┐ │ id │ name │ status │ uptime │ ├────────────┼─────────────┼─────────┼────────┤ │ agent-001 │ My Agent │ Running │ 2h 15m │ └────────────┴─────────────┴─────────┴────────┘ Total: 1 agent(s)
mofa agent list --output-format json
[ { "id" : "agent-001" , "name" : "My Agent" , "status" : "Running" , "uptime" : "2h 15m" } ]
mofa agent list --output-format table
Produces a formatted table optimized for terminal display.
Debugging Enable verbose logging:
# Enable verbose mode mofa --verbose agent start my-agent # Or use environment variable export RUST_LOG = debug mofa agent start my-agent
Common Workflows Creating and Starting an Agent # Create new project mofa new my-agent cd my-agent # Set up environment export OPENAI_API_KEY = "sk-..." # Build and run cargo run
Managing Running Agents # List all agents mofa agent list # Check specific agent status mofa agent status my-agent # View logs mofa agent logs my-agent --tail # Stop agent mofa agent stop my-agent
Session Management # List all sessions mofa session list # Filter by agent mofa session list --agent my-agent # Show session details mofa session show session-123 # Export session mofa session export session-123 -o session.json --format json
Getting Help Get help for any command:
# General help mofa --help # Command-specific help mofa agent --help mofa agent start --help # Show version mofa --version
Next Steps
Create Projects Learn about project templates and scaffolding
Manage Agents Start, stop, and monitor agents
Configuration Configure MoFA settings
Examples Explore example projects