CLI Reference

CLI Reference#

MassGen Command Line Interface reference.

Basic Usage#

massgen [OPTIONS] ["<your question>"]

Default Behavior (No Arguments):

When running massgen with no arguments, configs are auto-discovered with this priority:

  1. .massgen/config.yaml (project-level config in current directory)

  2. ~/.config/massgen/config.yaml (global default config)

  3. Launch setup wizard if no config found

First-Time Setup:

The wizard consists of two steps:

  1. API Key Setup (if no cloud provider keys detected)

    • Prompts for OpenAI, Anthropic, Google, or other cloud provider API keys

    • Saves to ~/.config/massgen/.env

    • Skipped if keys already exist

  2. Configuration Setup

    • Option to browse ready-to-use configs/examples

    • Option to build from templates (Simple Q&A, Research, Code & Files, etc.)

    • Asks “Save as default?” when browsing existing configs

    • Launches directly into interactive mode

After Setup:

  • No arguments → Starts multi-turn conversation mode if default config chosen

  • With question → Runs single query using default config

CLI Parameters#

Parameter

Description

--config PATH

Path to YAML configuration file with agent definitions, model parameters, backend parameters and UI settings. With --quickstart, this value is treated as the output filename under .massgen/ (for example, --quickstart --config team-config saves .massgen/team-config.yaml)

--select

Interactively select from available configurations (user configs, project configs, current directory, package examples). Uses hierarchical navigation: category → config

--backend TYPE

Backend type for quick setup without config file. Options: claude, claude_code, gemini, grok, openai, azure_openai, zai

--model NAME

Model name for quick setup (e.g., gemini-2.5-flash, gpt-5-nano). Mutually exclusive with --config

--system-message TEXT

System prompt for the agent in quick setup mode. Omitted if --config is provided

--cwd-context {ro,rw,read,write}

Add the current working directory to orchestrator.context_paths for this run. ro/read grants read-only access, rw/write grants write permission

--plan

Planning-only mode. Agents create a structured task plan without auto-executing it

--plan-depth {dynamic,shallow,medium,deep}

Controls plan granularity for --plan mode

--plan-steps N

Optional explicit task-count target for planning output (must be > 0)

--plan-chunks N

Optional explicit chunk-count target for planning output (must be > 0)

--broadcast {human,agents,false}

Planning collaboration mode: ask user questions, coordinate among agents, or run fully autonomous

--plan-and-execute

Full workflow: create a plan, then execute it immediately

--execute-plan PLAN_PATH

Execute an existing plan by plan directory, plan ID, or latest

--no-display

Disable real-time streaming UI coordination display (fallback to simple text output)

--no-logs

Disable real-time logging

--debug

Enable debug mode with verbose logging. Debug logs saved to agent_outputs/log_{time}/massgen_debug.log

--session-id ID

Load memory from a previous session by ID (e.g., session_20251028_143000). Allows continuing conversations with memory context from prior runs. Use with --list-sessions to find available sessions

--list-sessions

List all available memory sessions with their metadata (session IDs, timestamps, models, status). Sessions are automatically tracked in ~/.massgen/sessions.json

--web

Start the WebUI server instead of the terminal UI. Opens a browser-based interface with real-time agent streaming, vote visualization, and workspace browsing

--web-host HOST

Host address for the WebUI server (default: 127.0.0.1). Use 0.0.0.0 to allow external connections

--web-port PORT

Port for the WebUI server (default: 8000)

--no-browser

Don’t auto-open browser when using --web with a question. Useful for automation or when running on servers

--output-file PATH

Write final answer to specified file path. Works in any mode (automation, interactive, etc.). Useful for capturing agent responses in scripts or pipelines

--logfire

Enable Logfire observability for structured tracing of LLM calls, tool executions, and orchestration. Requires Logfire token (via logfire auth login or LOGFIRE_TOKEN env var). See Logging & Debugging for setup details

"<your question>"

Optional single-question input. If omitted, MassGen enters interactive chat mode

Mode Settings#

These flags mirror the TUI mode bar toggles, allowing CLI control of execution modes.

Parameter

Description

--single-agent [AGENT_ID]

Single-agent mode. Uses only one agent from the config. Optionally specify an agent ID; defaults to the first agent if omitted

--coordination-mode {parallel,decomposition}

Coordination mode: parallel (voting-based, default) or decomposition (subtask-based). Overrides coordination_mode from config

--quick

Quick mode: disable refinement. Agents produce one answer with no voting loop. Equivalent to TUI “Refine OFF” toggle

--personas {off,perspective,implementation,methodology}

Enable parallel persona generation with specified diversity mode. off disables persona generation. Requires parallel coordination mode

Examples#

Default Configuration Mode#

# First time: Launch setup wizard
massgen

# After setup: Start interactive conversation
massgen

# Run single query with default config
massgen "What is machine learning?"

Interactive Config Selection#

# Browse and select from available configurations
massgen --select

# After selection, optionally provide a question
massgen --select "Your question here"

# The selector shows configs from:
# - User configs: ~/.config/massgen/agents/
# - Project configs: .massgen/*.yaml
# - Current directory: *.yaml
# - Package examples: Built-in example configs

Quick Single Agent#

# Fastest way to test - no config file
massgen --model claude-3-5-sonnet-latest "What is machine learning?"
massgen --model gemini-2.5-flash "Explain quantum computing"

With Specific Backend#

massgen \
  --backend gemini \
  --model gemini-2.5-flash \
  "What are the latest developments in AI?"

Multi-Agent with Config#

# Recommended: Use YAML config for multi-agent
massgen \
  --config @examples/basic/multi/three_agents_default.yaml \
  "Analyze the pros and cons of renewable energy"

Interactive Mode#

# Omit question to enter interactive chat mode
massgen --model gemini-2.5-flash

# Multi-agent interactive
massgen \
  --config @examples/basic/multi/three_agents_default.yaml

Quick CWD Context Access#

# Add current directory as read-only context
massgen --config my_config.yaml --cwd-context ro "Review this codebase"

# Add current directory as writable context
massgen --config my_config.yaml --cwd-context rw "Apply the requested refactor"

Note

In the Textual TUI, --cwd-context initializes the same CWD context state as the Ctrl+P toggle. In Execute mode, Ctrl+P is intentionally blocked to avoid changing context scope mid-execution.

Mode Settings#

# Quick mode: one answer per agent, no refinement loop
massgen --quick --config my_config.yaml "Summarize this paper"

# Single agent from a multi-agent config
massgen --single-agent --config my_config.yaml "Quick question"

# Single agent by ID
massgen --single-agent agent_b --config my_config.yaml "Quick question"

# Fastest: single agent + quick mode
massgen --single-agent --quick --config my_config.yaml "What is 2+2?"

# Persona-diverse parallel execution
massgen --personas perspective --config my_config.yaml "Design a logo"

# Decomposition mode (subtask-based)
massgen --coordination-mode decomposition --config my_config.yaml "Build a web app"

Debug Mode#

massgen \
  --debug \
  --config @examples/basic/multi/three_agents_default.yaml \
  "Your question here"

Disable UI#

# Simple text output instead of rich terminal UI
massgen \
  --no-display \
  --config config.yaml \
  "Question"

Session Management#

# List available memory sessions
massgen --list-sessions

# Load session from previous run
massgen --session-id session_20251028_143000 \
  "What did we discuss about the backend architecture?"

# Interactive mode with previous session
massgen --session-id session_20251028_143000 \
  --config my_config.yaml

# Session can also be specified in YAML config
# Add to your config.yaml:
#   session_id: "session_20251028_143000"

WebUI Mode#

# Start WebUI on default localhost:8000
massgen --web

# Custom host and port (for external access)
massgen --web --web-host 0.0.0.0 --web-port 3000

# With a specific config
massgen --web --config @examples/basic/multi/three_agents_default

# Combine with debug mode
massgen --web --debug --config my_config.yaml

OpenAI-Compatible HTTP Server (massgen serve)#

Run MassGen as an OpenAI-compatible HTTP API (FastAPI + Uvicorn).

Endpoints:

  • GET /health - Health check endpoint

  • POST /v1/chat/completions - OpenAI-compatible chat completions (non-streaming only)

Note

Streaming (stream: true) is not yet supported. The server will return HTTP 501 if streaming is requested. Use stream: false for all requests.

# Start server (defaults: host 0.0.0.0, port 4000)
massgen serve

# Custom bind
massgen serve --host 127.0.0.1 --port 4000

# Provide a default config
massgen serve --config path/to/config.yaml

# Enable auto-reload for development
massgen serve --reload

# Health check
curl http://localhost:4000/health

# OpenAI-compatible Chat Completions
# Note: When running with --config, the "model" parameter is ignored
# to ensure the server uses the agent team defined in your YAML.
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"massgen","messages":[{"role":"user","content":"hi"}],"stream":false}'

Response Format:

The server returns responses with the final synthesized answer in content and all agent traces in reasoning_content:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "The final answer from the agent team.",
      "reasoning_content": "[system] Starting coordination...\n[agent_1] Analyzing...\n[orchestrator] Vote: agent_1"
    },
    "finish_reason": "stop"
  }]
}

Environment variables (optional):

  • MASSGEN_SERVER_HOST (default: 0.0.0.0)

  • MASSGEN_SERVER_PORT (default: 4000)

  • MASSGEN_SERVER_DEFAULT_CONFIG (default: unset)

  • MASSGEN_SERVER_DEBUG (default: false)

Output to File#

# Save agent response to a file
massgen --output-file results.txt "Summarize the key points of machine learning"

# With config and output file
massgen --config my_config.yaml --output-file report.md "Generate a project report"

Logfire Observability#

# Enable structured tracing with Logfire
massgen --logfire --config your_config.yaml "Your question"

# Combine with debug mode for maximum observability
massgen --logfire --debug --config your_config.yaml "Your question"

# Or enable via environment variable
export MASSGEN_LOGFIRE_ENABLED=true
massgen --config your_config.yaml "Your question"

See Logging & Debugging for detailed Logfire setup instructions.

Additional Commands#

Log Analysis (massgen logs)#

Analyze and browse session logs without manual file navigation.

# Summary of most recent run
massgen logs

# Full tool breakdown
massgen logs tools

# List recent runs
massgen logs list

# Open log directory in file manager
massgen logs open

Subcommand

Description

massgen logs or massgen logs summary

Display run summary with tokens, rounds, and top tools

massgen logs tools

Full tool breakdown table sorted by execution time

massgen logs tools --sort calls

Sort tools by call count instead of time

massgen logs list

List recent runs with timestamps, costs, questions, and analysis status

massgen logs list --analyzed

Show only logs with ANALYSIS_REPORT.md

massgen logs list --unanalyzed

Show only logs without analysis

massgen logs list --limit 20

Show more runs (default: 10)

massgen logs analyze

Generate analysis prompt for use in coding CLIs

massgen logs analyze --mode self

Run multi-agent self-analysis using a preset MassGen team (customizable via --config)

massgen logs open

Open log directory in system file manager

Options:

Option

Description

--log-dir PATH

Analyze a specific log directory instead of the most recent

--json

Output raw JSON for scripting

--mode {prompt,self}

For analyze: prompt (default) outputs a prompt; self runs multi-agent analysis

--ui {automation,rich_terminal,webui}

For analyze --mode self: UI mode (default: rich_terminal)

--config PATH

For analyze --mode self: Custom analysis config file

Share Session (massgen export)#

Share a session via GitHub Gist for easy collaboration.

# Share the most recent session
massgen export

# Share a specific session
massgen export log_20251218_134125_867383

Prerequisites: Requires GitHub CLI (gh) to be installed and authenticated.

# Install gh (macOS)
brew install gh

# Authenticate
gh auth login

Output:

Sharing session from: .massgen/massgen_logs/log_20251218_134125/turn_1/attempt_1
Collecting files...
Uploading 45 files (1,234,567 bytes)...

Share URL: https://massgen.github.io/MassGen-Viewer/?gist=abc123def456

Anyone with this link can view the session (no login required).

The URL opens the MassGen Viewer with the session’s coordination timeline, answers, votes, and tool usage.

Session Viewer (massgen viewer)#

View any MassGen session in the full Textual TUI (read-only). Useful for observing --automation runs, replaying completed sessions, and monitoring cloud/CI runs.

# View the most recent session
massgen viewer

# View a specific log directory
massgen viewer /path/to/log_dir

# Interactive session picker
massgen viewer --pick

# Replay at real-time speed (default: instant)
massgen viewer /path/to/log_dir --replay-speed 1

# View in browser via textual-serve
massgen viewer /path/to/log_dir --web --port 9000

Option

Description

log_dir

Path to log directory (positional, optional). Default: most recent session

--turn N

View a specific turn (default: latest)

--attempt N

View a specific attempt (default: latest)

--replay-speed FLOAT

Playback speed for completed sessions. 0 = instant (default), 1 = real-time, 2 = 2x speed

--pick

Interactively pick from recent sessions

--web

Serve the viewer TUI in a browser via textual-serve

--port PORT

Port for --web mode (default: 8000)

The viewer shows the exact same TUI as a normal interactive run — agent panels, tool calls, votes, and final presentation — but in read-only mode with the input area hidden.

Manage Shared Sessions (massgen shares)#

List and manage your shared sessions.

# List your shared sessions
massgen shares list

# Delete a shared session
massgen shares delete <gist_id>

See Also#