Spawnosaurus CLI

Spawnosaurus is a Grok-powered agent command-line tool that can either execute tasks directly via Grok or run plan-driven workloads materialised by ExeCode.io in the Vercel Sandbox. Think of it as the command-line twin of ExeCode.io’s browser experience: fast local setup, automated plan execution, and structured results that are safe to pipe into other tooling.

TL;DR for New Developers

• Interactive REPL mode – Start a continuous session with conversation history, multi-line paste support, and command history navigation. Perfect for iterative development.
• Skip manual orchestration – feed Spawnosaurus an ExeCode.io plan and it runs every task (or a single task) with the correct dependencies.
• Bring-your-own prompt – run one-off Grok prompts from the terminal and capture structured JSON output.
• Safety-first tooling – Spawnosaurus limits Grok to a vetted toolbelt (read, write, patch, bash, etc.) so file edits are predictable and auditable.
• Fits into CI/CD – deterministic JSON output, exit codes, and summary metadata make it easy to plug into automated pipelines.

Quick Start

1. Install dependencies

   cd spawnosaurus-cli
   npm install
   npm run build

2. Authenticate (required for Grok calls)

   echo "XAI_API_KEY=sk-your-grok-key" >> .env
   # or export XAI_API_KEY=sk-your-grok-key

3. Run your first command

   # Interactive REPL mode – start a continuous session
   spawnosaurus repl
   # or, using the shorter alias
   spawno repl
      
   # Direct mode – ask Grok to do something immediately
   spawnosaurus "Draft a migration plan for converting Jest tests to Vitest" --output json
   # or, using the shorter alias
   spawno "Draft a migration plan for converting Jest tests to Vitest" --output json

4. Run an ExeCode.io plan

   spawnosaurus hatch \
     --plan .agent/plan.json \
     --output json
   # alias works here too
   spawno hatch \
     --plan .agent/plan.json \
     --output json

Prefer a global install? npm install -g spawnosaurus-cli drops the spawnosaurus binary (and spawno alias) onto your PATH.

Features

• 🎯 Interactive REPL Mode – Continuous session with conversation history, multi-line paste, and command history navigation
• ⚡️ Zero-config TypeScript CLI build with tsup
• 🤖 Grok 4 Fast Reasoning integration via Vercel AI SDK
• 🧠 Plan-driven hatch subcommand that iterates every task in an ExeCode.io plan
• 🛠️ Rich LLM toolbelt (bash, read, write, edit, patch, list, glob, grep, todo, webfetch)
• 📝 JSON or text output formats for easy downstream tooling

Requirements

• Node.js v18.18 or newer
• REPL mode (repl): Grok API key (XAI_API_KEY with optional legacy alias GROK_API_KEY)
• Plan mode (hatch): plan + task JSON files written by ExeCode.io (usually .agent/plan.json and .agent/tasks/<id>.json) + Grok API key
• Direct mode: Grok API key (XAI_API_KEY with optional legacy alias GROK_API_KEY)

How It Works

1. REPL mode (repl) – Start an interactive session that maintains conversation history across commands. Perfect for iterative development where you need context from previous interactions. Supports multi-line paste, command history, and special session management commands.
2. Plan mode (hatch) – ExeCode.io produces a plan (.agent/plan.json) and per-task artifacts. Spawnosaurus reads the plan, replays each task in order, and exposes a curated toolbelt to Grok so that the run stays within the sandboxed workspace.
3. Direct mode – Skip the plan and run a single Grok-powered task inline. Great for one-off fixes, docs, or research queries.
4. Structured output – Every task must call submit_task_result with a schema-validated payload, ensuring Spawnosaurus always emits machine-readable JSON.
5. Streaming feedback – Task logs, stdout/stderr, and progress summaries are streamed to the console for fast feedback loops.
6. Agent-like behavior – Spawnosaurus uses an iterative Observe→Think→Act→Repeat workflow, continues until task completion (not fixed step limits), and self-corrects when errors occur. See SPAWNOSAURUS_AGENT_IMPROVEMENTS.md for details.

Execution Modes

Spawnosaurus supports two execution modes for task execution:

Direct Mode (Default)

Direct Mode uses Grok to directly call a set of predefined tools (bash, read, write, etc.) for efficient, multi-step operations within a single LLM turn. This is the preferred default mode for most tasks.

When to use:

• Simple file operations (create, read, edit)
• Running shell commands
• Installing packages
• Quick code generation
• Most day-to-day development tasks

Example:

spawnosaurus "Create a hello.txt file with content 'Hello World'"

OpenCode Mode (Optional)

OpenCode Mode uses the OpenCode CLI for complex scaffolding tasks. Spawnosaurus spawns the OpenCode CLI as a subprocess, which handles its own LLM orchestration and tool execution.

When to use:

• Scaffolding full-stack applications
• Multi-file project setup
• Complex project bootstrapping
• Tasks requiring extensive code generation

Example:

spawnosaurus --opencode "scaffold a full-stack React app with Express backend"

Requirements:

• OpenCode CLI must be installed: npm install -g @opencode-ai/cli
• Provider credentials (OpenRouter or XAI API key)

Mode Selection:

• Explicit: Use --opencode flag to force OpenCode mode
• Auto-detection: Spawnosaurus automatically detects complex tasks (scaffold, multi-file, full-stack, project setup, bootstrap) and uses OpenCode mode
• Default: Simple tasks use Direct mode automatically

Provider Configuration:

Spawnosaurus supports two providers for OpenCode mode:

1. OpenRouter (Preferred): Uses model x-ai/grok-4.1-fast via OpenRouter

   spawnosaurus --opencode --openrouter-api-key sk-... "scaffold a React app"
   # or via environment variable
   export OPENROUTER_API_KEY=sk-...
   spawnosaurus --opencode "scaffold a React app"

2. XAI Direct: Uses model grok-4.1-fast directly from XAI

   spawnosaurus --opencode --xai-api-key xai-... "scaffold a React app"
   # or via environment variable
   export XAI_API_KEY=xai-...
   spawnosaurus --opencode "scaffold a React app"

CLI Flags:

• --opencode: Use OpenCode mode (for complex tasks)
• --openrouter-api-key <key>: OpenRouter API key (for OpenCode mode via OpenRouter)
• --openrouter-model <model>: OpenRouter model (defaults to x-ai/grok-4.1-fast)
• --xai-api-key <key>: XAI API key (alternative to OpenRouter, uses model grok-4.1-fast)

Environment Variables:

• OPENROUTER_API_KEY: OpenRouter API key (fallback if flag not provided)
• OPENROUTER_MODEL: OpenRouter model (defaults to x-ai/grok-4.1-fast if not provided)
• XAI_API_KEY: XAI API key (alternative to OpenRouter, uses model grok-4.1-fast)

Provider Selection Priority:

1. OpenRouter (if OPENROUTER_API_KEY or --openrouter-api-key provided)
2. XAI direct (if XAI_API_KEY or --xai-api-key provided, and no OpenRouter)
3. Default: OpenRouter with x-ai/grok-4.1-fast if OPENROUTER_API_KEY available

Installation

# From the project root
cd spawnosaurus-cli
npm install
npm run build

Global install (optional):

npm install -g spawnosaurus-cli

Uninstall:

npm uninstall              # local
npm uninstall -g spawnosaurus-cli  # global

Verify the installed version:

spawnosaurus --version
# or
spawno --version

Usage Modes

Mode comparison

| Mode | When to use it | Required input | Typical command | |------|----------------|----------------|-----------------| | REPL (repl) | Interactive session for continuous command execution with conversation history | Grok API key | spawnosaurus repl (alias: spawno) | | Plan (hatch) | Replay an ExeCode.io plan, honour task dependencies, produce CI-friendly JSON | .agent/plan.json (+ task files) | spawnosaurus hatch --plan .agent/plan.json --output json (alias: spawno) | | Direct | Fire off a one-liner Grok task from your terminal | Prompt text + Grok API key | spawnosaurus "Explain this stack trace" --output json (alias: spawno) |

Plan execution workflow

ExeCode.io writes the plan and task artifacts into the sandbox before invoking the CLI. By default spawnosaurus hatch executes every task sequentially and stops on failure:

spawnosaurus hatch \
  --plan .agent/plan.json \
  --output json

Narrow the run to a single task:

spawnosaurus hatch \
  --plan .agent/plan.json \
  --task spawnosaurus-smoke-task \
  --output json

Key flags:

• --plan <path>: Path to the agent plan JSON file (required)
• --task <id>: Execute a single task (omit to run the full plan)
• --all: Explicitly run every task (default behaviour)
• --task-file <path>: Override the task JSON location
• -k, --api-key: Grok API key (defaults to XAI_API_KEY, falls back to GROK_API_KEY)
• -m, --model: Model identifier (grok-4-1-fast-reasoning default)
• -o, --output: text or json (defaults to text)
• --opencode: Use OpenCode mode for complex scaffolding tasks
• --openrouter-api-key <key>: OpenRouter API key (for OpenCode mode via OpenRouter)
• --openrouter-model <model>: OpenRouter model (defaults to x-ai/grok-4.1-fast)
• --xai-api-key <key>: XAI API key (alternative to OpenRouter for OpenCode mode)

Spawnosaurus now executes every plan task through a tool-enabled Grok workflow. Available tools:

| Tool | Purpose | |------------|----------------------------------------------------------------| | bash | Execute shell commands within the workspace | | read | Read file contents | | write | Create or overwrite files | | edit | Apply exact string replacements in an existing file | | patch | Apply unified diff patches | | list | List directory contents | | glob | Match files using glob patterns | | grep | Search files with regular expressions (ripgrep fallback) | | todowrite/todoread | Persist task-level todos in .agent/spawnosaurus-todos.json | | webfetch | Retrieve remote web content |

Each task responds with structured JSON (status, summary, details, nextSteps) and the CLI prints an aggregated summary (or emits full JSON when --output json is selected).

Structured Output (v0.4.0+)

As of version 0.4.0, Spawnosaurus uses tool-based structured output to ensure reliable JSON responses. Instead of prompting Grok to return freeform JSON (which can include extra text), the CLI now requires Grok to call a submit_task_result tool with a predefined Zod schema:

{
  status: 'success' | 'failed' | 'blocked',
  summary: string,        // Brief description of outcome
  details: string[],      // List of key actions taken
  nextSteps: string[],    // Optional follow-up recommendations
  stdout?: string,        // Optional captured output
  stderr?: string         // Optional error output
}

This guarantees parseable output for every task and makes Spawnosaurus output safe for automation and CI/CD pipelines. All tool invocations are also logged and can be displayed in the ExeCode.io UI.

ℹ️ ExeCode.io's sandbox installs the CLI directly from npm (spawnosaurus-cli). Keep the published package up to date so new sandboxes always receive the latest binary.

2. Direct Task Execution

# Human-readable summary (default)
spawnosaurus "Draft a migration plan for converting Jest tests to Vitest"

# Structured machine-friendly output
spawnosaurus "Draft a migration plan for converting Jest tests to Vitest" --output json

This mode allows quick prompting without plan artifacts. Use --output json only when you need deterministic JSON for downstream automation; otherwise enjoy the default text summary. Provide a Grok API key in both cases.

3. Interactive REPL Mode

The REPL mode provides an interactive terminal experience where you can continuously execute commands without restarting the CLI. It maintains conversation history across commands, supports multi-line paste, and offers command history navigation.

# Start interactive REPL
spawnosaurus repl

# With custom model
spawnosaurus repl --model grok-4

# With JSON output
spawnosaurus repl --output json

Key Features:

• Conversation History: Maintains context across multiple commands, allowing for follow-up questions and iterative development
• Multi-line Paste: Automatically detects and handles pasted multi-line code blocks
• Command History: Navigate previous commands with up/down arrow keys (persisted to ~/.spawnosaurus-history)
• Special Commands: Built-in commands for managing the session

Special Commands:

• .exit, .quit, exit, quit - Exit the REPL
• .clear - Clear conversation history
• .history - Show conversation history
• .help - Show available commands
• .editor - Open external editor for multi-line input (uses $EDITOR env var)
• .model [model] - Show or change the AI model
• .output [format] - Show or change output format (text/json)

Usage Tips:

• Multi-line Paste: Simply paste multi-line code directly - it will be detected automatically
• Cancel Operations: Press Ctrl+C to cancel a running command
• Exit: Use Ctrl+D, .exit, or type exit to quit
• Editor Mode: Use .editor to open your preferred editor ($EDITOR) for composing longer prompts
• Conversation Context: The REPL maintains conversation history, so you can reference previous responses in follow-up questions

Example Session:

$ spawnosaurus repl
🚀 Spawnosaurus Interactive REPL
Type .help for available commands or start typing your prompt

spawno> Create a simple hello world function in Python
✅ Task completed successfully
...

spawno> Now add error handling to that function
✅ Task completed successfully
...

spawno> .history
Conversation History:
1. 👤 user: Create a simple hello world function in Python
2. 🤖 assistant: Task completed successfully...
3. 👤 user: Now add error handling to that function
4. 🤖 assistant: Task completed successfully...

spawno> .exit
👋 Goodbye!

Command History:

Command history is automatically saved to ~/.spawnosaurus-history and loaded when you start a new REPL session. Use arrow keys to navigate through previous commands.

Troubleshooting

• Error: XAI_API_KEY not set – Create a .env file or export the variable in your shell (export XAI_API_KEY=...). Global installs should add it to .zshrc/.bashrc.
• Plan file not found – Confirm you are in the workspace root where .agent/plan.json lives, or pass an absolute path to --plan.
• Task JSON missing – Use --task-file when task artifacts are stored outside the default .agent/tasks/<id>.json directory.
• npm install dependency errors – Spawnosaurus continues even if dependency installation fails; inspect the error log in the task summary and rerun after fixing package issues.
• Unstructured output – Upgrade to Spawnosaurus v0.4.0+ to guarantee tool-enforced JSON responses.
• REPL not starting – Ensure you have a valid XAI_API_KEY set. The REPL requires an API key to initialize the session.
• Command history not working – Command history is saved to ~/.spawnosaurus-history. Ensure you have write permissions to your home directory.

Environment Variables

| Variable | Purpose | |----------|---------| | XAI_API_KEY | Primary Grok credential (required for REPL, direct mode, and plan execution). Also used for OpenCode mode when OpenRouter is not available. | | GROK_API_KEY | Optional legacy alias for XAI_API_KEY | | OPENROUTER_API_KEY | OpenRouter API key for OpenCode mode (preferred, uses model x-ai/grok-4.1-fast) | | OPENROUTER_MODEL | OpenRouter model for OpenCode mode (defaults to x-ai/grok-4.1-fast) | | EDITOR | External editor for REPL .editor command (defaults to nano if not set) |

Setting credentials

Local development (within the spawnosaurus-cli folder):

cd spawnosaurus-cli
echo "XAI_API_KEY=sk-your-grok-key" >> .env
npm run build

Alternatively export it for the current shell session:

cd spawnosaurus-cli
export XAI_API_KEY=sk-your-grok-key
spawnosaurus --version

Global installs: add the key to your shell profile (e.g. ~/.zshrc, ~/.bashrc) so spawnosaurus can pick it up anywhere:

echo 'export XAI_API_KEY=sk-your-grok-key' >> ~/.zshrc
source ~/.zshrc
spawnosaurus --version

You can always override the environment by passing --api-key to any command:

spawnosaurus hatch --plan .agent/plan.json --api-key sk-your-grok-key

Publishing Updates

After making changes, publish a new version to npm so the sandbox can install it:

npm run build
npm publish

Update the version in the ExeCode.io repository when you release a new build.

License

MIT © ExeCode.io