Skip to main content

​
Overview

The Longshot CLI provides a command-line interface for running the orchestrator with human-readable logs. It handles runtime resolution, log formatting, and optional dashboard integration.

​
Installation

pip install longshot

​
Basic Usage

longshot "Build a playable MVP of Minecraft"
Backward-compatible invocation: 
python main.py "Build a playable MVP of Minecraft"

​
Command Syntax

longshot REQUEST [OPTIONS]

​
Arguments

request (required)
  • Natural language build request
  • Examples:
    • "Build Minecraft according to SPEC.md"
    • "Implement user authentication system"
    • "Add real-time chat feature"

​
Options

--dashboard
  • Launch the Rich TUI dashboard alongside the orchestrator
  • Shows real-time progress visualization
  • Default: disabled
longshot "Build a web app" --dashboard
--reset
  • Reset target repo to initial commit before running
  • Executes scripts/reset-target.sh
  • Useful for clean test runs
  • Default: disabled
longshot "Rebuild from scratch" --reset
--debug
  • Enable debug logging (LOG_LEVEL=debug)
  • Shows verbose output with timestamps in milliseconds
  • Increases truncate limits for error messages
  • Default: disabled
longshot "Debug this issue" --debug
--version
  • Display CLI version and exit
longshot --version

​
Output Formatting

​
Log Levels

The CLI formats logs with color-coded levels:
  • DEBUG - Dim gray (only with --debug)
  • INFO - Green
  • WARN - Yellow
  • ERROR - Red

​
Agent Styles

Different agents are color-coded:
  • planner - Cyan
  • orchestrator - Magenta
  • monitor - Blue
  • worker-pool - Magenta
  • reconciler - Yellow
  • merge-queue - Blue
  • llm-client - Dim
  • main - White

​
Log Format

[HH:MM:SS] LEVEL AGENT         MESSAGE data=value
Example: 
15:42:33 INFO  planner        Task created taskId=agent-001 desc=Implement auth
15:42:34 INFO  worker-pool    Dispatching task to ephemeral sandbox taskId=agent-001
15:43:12 INFO  planner        Task completed taskId=agent-001 status=complete

​
Metrics Bar

Real-time metrics displayed during execution: 
[0:05:23]  workers=12  pending=8  done=45  failed=2  commits/hr=180  merged=42  tokens=1.2M
Metrics Include:
  • workers - Active workers (cyan)
  • pending - Pending tasks (yellow)
  • done - Completed tasks (green)
  • failed - Failed tasks (red)
  • commits/hr - Commits per hour rate (cyan)
  • merged - Successfully merged branches (green)
  • merge-q - Merge queue depth (yellow, if > 0)
  • merge-fail - Failed merges (red, if > 0)
  • tokens - Total tokens used (dim)
  • in-flight - Estimated in-flight tokens (dim, if > 0)

​
Run Summary

Displayed at completion (success or interrupt): 
═══ Run Summary ═══
  Duration:  1h 23m 45s
  Tasks:     156 done / 3 failed / 159 total
  Merges:    148 merged / 2 failed / 4 conflicts
  Throughput: 112 commits/hr  |  2,450,000 tokens
  Log:       /path/to/logs/run-20260303-154233.ndjson
  Traces:    /path/to/logs/run-20260303-154233.trace.ndjson
  LLM log:   /path/to/logs/run-20260303-154233.llm.ndjson

​
Runtime Resolution

The CLI automatically resolves the runtime:

​
Local Development

If running from source with local build: 
packages/orchestrator/dist/main.js exists → use local runtime

​
Downloaded Runtime

Otherwise downloads and caches runtime bundle:
  1. Cache location: ~/.longshot/runtime/{version}/
  2. Download from: GitHub releases
  3. Auto-install dependencies: npm install --omit=dev
Environment Variables:
  • LONGSHOT_RUNTIME_URL - Override runtime download URL
  • LONGSHOT_CACHE_DIR - Override cache directory (default: ~/.longshot/runtime)
  • LONGSHOT_RELEASE_REPO - Override GitHub repo (default: andrewcai8/longshot)
  • LONGSHOT_PROMPTS_ROOT - Override prompts directory

​
Truncation Limits

The CLI truncates long data fields to keep logs readable:
ModeLimit
Default200 chars
Error/Warn500 chars
Debug (--debug)2000 chars

​
Signal Handling

The CLI gracefully handles interrupt signals:
  • SIGINT (Ctrl+C) - Graceful shutdown with summary
  • SIGTERM - Graceful shutdown with summary
On shutdown:
  1. Display shutdown message
  2. Show run summary with metrics
  3. Terminate orchestrator process
  4. Terminate dashboard (if running)
  5. Exit

​
Exit Codes

  • 0 - Orchestrator finished successfully
  • Non-zero - Orchestrator error (displays error message)
  • Script errors - Propagated from reset script
Log file paths are underlined for easy terminal navigation: 
  Log:     /home/user/project/logs/run-20260303-154233.ndjson
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

​
Dashboard Integration

When --dashboard is enabled:
  1. CLI spawns dashboard process: python dashboard.py --stdin
  2. Pipes orchestrator stdout to dashboard stdin
  3. Dashboard renders TUI in parallel
  4. Both processes share the same log stream

​
Examples

​
Standard Run

longshot "Build a todo app with React and TypeScript"

​
With Dashboard

longshot "Implement GraphQL API" --dashboard

​
Clean Reset

longshot "Start fresh implementation" --reset

​
Debug Mode

longshot "Fix authentication bug" --debug

​
Combined Options

longshot "Build complete e-commerce platform" --dashboard --debug

​
Programmatic Usage

from main import run

exit_code = run(
    request="Build a web scraper",
    with_dashboard=True,
    reset=False,
    debug=False
)

Build docs developers (and LLMs) love

Get started for freeTalk to us