Skip to content

cli-reference.md

Latest commit

 

History

History
183 lines (134 loc) · 5.58 KB

cli-reference.md

File metadata and controls

183 lines (134 loc) · 5.58 KB
Raw

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

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 --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

harness

Harness-engineering workflow for structured multi-step tasks:

ggcode harness create <title>          # Create a task
ggcode harness list                    # List tasks
ggcode harness show <id>               # Show task details
ggcode harness start <id>              # Start working on a task
ggcode harness monitor                 # Monitor active work

mcp

MCP server management:

ggcode mcp list                        # List configured MCP servers
ggcode mcp add <name> <command>        # Add an MCP server
ggcode mcp remove <name>               # Remove an MCP server

plugin

Manage gRPC and command plugins:

ggcode plugin list                     # List configured plugins
ggcode plugin install <name> <cmd...>  # Install a plugin (--env K=V, --type grpc|command)
ggcode plugin uninstall <name>         # Remove a plugin
ggcode plugin test <name>              # Test a plugin can start and handshake

See gRPC Plugins for the full guide.

im

IM integration management:

ggcode im list                         # List configured IM adapters

acp

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

ggcode acp                             # Start ACP server

llm-probe

Test LLM provider connectivity and list available models:

ggcode llm-probe                       # Test current provider

Status

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

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, --pipe <prompt> Non-interactive pipe mode
--resume [id] Resume a session
--resume-picker Open session picker
--new-session Skip auto-resume, always start a new session
-h, --help Show help