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
``bash
cd spawnosaurus-cli
npm install
npm run build
`
2. Authenticate (required for Grok calls)
`bash
echo "XAI_API_KEY=sk-your-grok-key" >> .env
# or export XAI_API_KEY=sk-your-grok-key
`
3. Run your first command
`bash
# 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
`bash
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/.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:

$3

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:
`bash
spawnosaurus "Create a hello.txt file with content 'Hello World'"
`

$3

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:
`bash
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
`bash
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
`bash
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 : OpenRouter API key (for OpenCode mode via OpenRouter)
- --openrouter-model : OpenRouter model (defaults to x-ai/grok-4.1-fast)
- --xai-api-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

`bash


From the project root


cd spawnosaurus-cli
npm install
npm run build
`

Global install (optional):

`bash
npm install -g spawnosaurus-cli
`

Uninstall:

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

Verify the installed version:

`bash
spawnosaurus --version


or


spawno --version
`

Usage Modes

$3

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

$3

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:

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

Narrow the run to a single task:

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

Key flags:

- --plan : Path to the agent plan JSON file (required)
- --task : Execute a single task (omit to run the full plan)
- --all: Explicitly run every task (default behaviour)
- --task-file : 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 : OpenRouter API key (for OpenCode mode via OpenRouter)
- --openrouter-model : OpenRouter model (defaults to x-ai/grok-4.1-fast)
- --xai-api-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).

$3

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:

`typescript
{
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.

$3

`bash


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

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.

`bash


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:

`bash
$ 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/.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) |

$3

Local development (within the spawnosaurus-cli folder):

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

Alternatively export it for the current shell session:

`bash
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:

`bash
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:

`bash
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:

`bash
npm run build
npm publish
``

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

License

MIT © ExeCode.io