cli-reference.md

CLI Reference

Run ggcode --help to see all available commands and flags for your version.

Core Commands

Interactive TUI (default)

ggcode                    # Launch interactive TUI
ggcode --bypass           # Start in bypass permission mode
ggcode --config <path>    # Use a specific config file

Pipe Mode

ggcode -p "prompt"        # Non-interactive: send prompt, print response
echo "fix typo" | ggcode  # Read from stdin

Additional pipe-mode flags:

• --allowedTools <name> — restrict tools (repeatable)
• --output <path> — write output to file (default: stdout)

Resume Session

ggcode --resume <id>      # Resume a specific session
ggcode --resume           # Auto-resume latest session
ggcode --resume-picker    # Open session picker
ggcode --new-session      # Skip auto-resume, always start fresh

--resume, --resume-picker, and --new-session are mutually exclusive.

Daemon Mode

ggcode daemon             # Start daemon (headless + IM gateway + lanchat)
ggcode daemon --follow    # Daemon with terminal follow display
ggcode daemon --bypass    # Daemon in bypass mode
ggcode daemon --background  # Fork to background
ggcode daemon --tunnel    # Start with mobile tunnel (QR code for GGCode Mobile)
ggcode daemon --new-session  # Skip auto-loading most recent session

The daemon automatically loads the most recent unlocked session on startup. Use --new-session to always start fresh. The daemon also initializes a lanchat Hub for LAN discovery and messaging.

Subcommands

Review & Promote:

Release (progressive delivery):

Monitor:

mcp

MCP (Model Context Protocol) server management:

ggcode mcp list                        # List configured MCP servers
ggcode mcp install                     # Interactive MCP setup wizard
ggcode mcp install <name> <command...> # Install a stdio MCP server
ggcode mcp install <name> -t http <url>  # Install an HTTP MCP server
ggcode mcp install <name> -t ws <url>  # Install a WebSocket MCP server
ggcode mcp uninstall <name>            # Remove an MCP server

Install options:

• -t, --type <stdio|http|ws> — transport type (default: stdio)
• -e, --env KEY=VALUE — environment variables (repeatable)
• --header KEY:VALUE — HTTP headers for http/ws transports (repeatable)

See MCP Guide for the full guide.

plugin

Manage gRPC and command plugins:

ggcode plugin list                     # List configured plugins
ggcode plugin install <name> <cmd...>  # Install a plugin
ggcode plugin uninstall <name>         # Remove a plugin
ggcode plugin test <name>              # Test a plugin can start and handshake

Install options:

• -e, --env KEY=VALUE — environment variables (repeatable)
• --type grpc|command — plugin type (default: grpc)

See gRPC Plugins for the full guide.

im

IM (Instant Messaging) adapter and binding management:

ggcode im status                       # Show overview of adapters + bindings
ggcode im list                         # List configured IM adapters
ggcode im list --json                  # JSON output for scripting
ggcode im bindings                     # List channel bindings
ggcode im bind <adapter>               # Bind a channel to an adapter
ggcode im unbind [<adapter>]           # Unbind a channel
ggcode im pair <adapter>               # Start interactive pairing
ggcode im share                        # Generate a PrivateClaw share link

Binding options:

• --channel <id> — target channel/thread ID
• --thread <id> — thread ID (platform-specific)
• --target <name> — target name for binding
• --workspace <path> — workspace path (default: current directory)

IM adapter configuration:

ggcode im config add [name]            # Add an adapter configuration
ggcode im config remove <name>         # Remove an adapter configuration
ggcode im config show <name>           # Show adapter details
ggcode im config show <name> --json    # JSON output
ggcode im config set <name> <key> <val>  # Modify a single setting

See IM Integration for the full guide.

acp

Agent Client Protocol support for editor integration (JetBrains, Zed, VS Code, etc.):

ggcode acp                             # Start ACP server (stdio JSON-RPC)
ggcode acp --vendor openai             # Override vendor
ggcode acp --endpoint <name>           # Override endpoint
ggcode acp --model <name>              # Override model

See ACP Guide for the full guide.

llm-probe

Test LLM provider connectivity, authentication, and token usage accuracy:

ggcode llm-probe                       # Test all configured endpoints
ggcode llm-probe --vendor zai          # Test only a specific vendor
ggcode llm-probe --endpoint <name>     # Test only a specific endpoint
ggcode llm-probe --model <name>        # Override model for all endpoints
ggcode llm-probe --list-models         # List models (no API call tests)
ggcode llm-probe --timeout 30          # 30s timeout per API call
ggcode llm-probe -v                    # Verbose: full request/response

status

Discover running ggcode instances and query their runtime state:

ggcode status              # List all running instances
ggcode status list         # Same as above (explicit)
ggcode status list --agent # Show only agent busy/idle status
ggcode status list --im    # Show only IM adapter status
ggcode status list --mobile # Show only mobile tunnel connections
ggcode status list --json  # JSON output for scripting
ggcode status get [workspace] # Detailed status for a specific workspace

The status command reads port files from ~/.ggcode/run/<sessionID>.json. Each running ggcode instance (TUI, daemon, desktop) writes its own port file keyed by session ID. Multiple instances in the same workspace each appear as separate entries.

Column	Description
PID	OS process ID
WORKSPACE	Working directory
SESSION	Session ID (truncated)
MODE	Permission mode
AGENT	busy or idle
IM	Number of IM adapters (online count in parentheses)
MOBILE	Mobile tunnel connection status
MODEL	Active LLM model

Stale port files (from crashed or killed processes) are automatically cleaned up on read.

report

Generate a self-contained HTML analytics report from all session JSONL files:

ggcode report                           # Generate report and open in browser
ggcode report -o ~/Desktop/report.html  # Specify output path
ggcode report --no-open                 # Generate without opening browser
ggcode report --sessions-dir /custom    # Override sessions directory

The report includes:

• Overview: daily token usage trends, workspace distribution, tool call summary, date range filter
• Sessions: sortable table with workspace/date filters, click-through to detail
• Session Detail: per-turn token bars, TTFT model comparison, draggable time range slider
• Daily Details: per-model token breakdown for any selected day (click daily chart bars)
• Performance: TTFT/duration histograms (P50/P95/P99), tool success rates

Charts use embedded Chart.js — fully offline, no CDN dependencies. The generated HTML file is self-contained and shareable.

completion

Generate shell completion scripts:

ggcode completion bash                 # Bash completion
ggcode completion zsh                  # Zsh completion
ggcode completion fish                 # Fish completion
ggcode completion powershell           # PowerShell completion

See Shell Completion for installation instructions.

version

ggcode version                         # Print version, commit, and build date

Global Flags

Flag	Description
--config <path>	Use a specific config file
--bypass	Start in bypass permission mode
-p, --prompt <prompt>	Non-interactive pipe mode
--allowedTools <name>	Restrict tools in pipe mode (repeatable)
--output <path>	Output file path (default: stdout)
--resume [id]	Resume a session
--resume-picker	Open session picker
--new-session	Skip auto-resume, always start a new session
-v	Shorthand for --version
-h, --help	Show help