GAIA Code CLI update (#147)

## Summary

This PR simplifies the `gaia-code` CLI by removing confusing subcommands
and creating a flat, intuitive interface.

## Problem

The current CLI has two subcommands (`run` and `init`) that don't make
sense:
- `run` is the only operation the CLI does - why require it?
- `init` should happen automatically, not manually
- Help was broken: `gaia-code --help` didn't show actual arguments (they
were hidden on the `run` subparser)
- Examples in help didn't work: showed `gaia-code "prompt"` but required
`gaia-code run "prompt"`

## Changes

### Removed All Subcommands
- ❌ Deleted `run` subcommand (unnecessary - it's the default operation)
- ❌ Deleted `init` subcommand (auto-initializes on first run now)
- ❌ Removed `cmd_init()` function (166 lines)
- ❌ Removed `_add_common_args()` helper (54 lines)
- ✅ All arguments now top-level on main parser

### Improved User Experience
- ✅ `gaia-code "Build me an app"` - works directly
- ✅ `gaia-code --interactive` - starts interactive mode
- ✅ `gaia-code --help` - shows ALL arguments (previously hidden)
- ✅ Auto-initialization - models load automatically on first use
- ✅ All examples in help actually work

### Code Quality
- **176 lines removed** (611 → 435 lines)
- Simpler argument parsing
- No more `sys.argv` manipulation hacks
- Cleaner code structure

## Testing

```bash
# All these now work as expected:
gaia-code "Build me a todo app"
gaia-code "Build me an app" --path ~/projects/myapp
gaia-code --interactive
gaia-code --list-tools
gaia-code --help  # Shows all arguments
```

## Breaking Change

The `run` subcommand has been removed. Users must update their commands:
- ❌ `gaia-code run "Build me an app"` (no longer works)
- ✅ `gaia-code "Build me an app"` (new syntax)

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: itomek

.claude/agents/api-documenter.md

@@ -111,7 +111,7 @@ Run GAIA agents for various AI tasks.
 
 ### Commands:
 - `gaia chat` - Interactive chat
-- `gaia code` - Code development
+- `gaia-code` - Code development
 - `gaia jira` - Issue management
 - `gaia blender` - 3D automation
 - `gaia mcp` - MCP server control
@@ -122,7 +122,7 @@ Run GAIA agents for various AI tasks.
 gaia llm "What is GAIA?"
 
 # Code generation
-gaia code "Create REST API"
+gaia-code "Create REST API"
 
 # Jira query
 gaia jira "show my open bugs"

.claude/agents/cli-developer.md

@@ -17,7 +17,7 @@ You are a GAIA CLI development specialist focused on command-line interface desi
 ```bash
 gaia llm          # Direct LLM queries
 gaia chat         # Interactive chat
-gaia code         # Code development agent
+gaia-code         # Code development agent
 gaia talk         # Voice interaction
 gaia blender      # 3D content creation
 gaia jira         # Issue management

docs/guides/code.mdx

@@ -83,7 +83,7 @@ The GAIA Code Agent turns a natural-language prompt into a working Next.js appli
 
   <Step title="Generate an app">
     ```bash
-    gaia code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10" --path movie-web-app
+    gaia-code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10" --path movie-web-app
     ```
   </Step>
 
@@ -101,31 +101,31 @@ The GAIA Code Agent turns a natural-language prompt into a working Next.js appli
 <Tabs>
   <Tab title="Workout Tracker">
     ```bash
-    gaia code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"
+    gaia-code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"
     ```
   </Tab>
 
   <Tab title="Restaurant Reviews">
     ```bash
-    gaia code "Build me a restaurant rating application in nextjs. I want to be able to put the location of the restaurant, the food that I ate, and my review"
+    gaia-code "Build me a restaurant rating application in nextjs. I want to be able to put the location of the restaurant, the food that I ate, and my review"
     ```
   </Tab>
 
   <Tab title="AI Tool Leaderboard">
     ```bash
-    gaia code "Build me an AI tool rater in nextjs where I can give the name of the AI programming tool, give it a score out of 10 for speed and quality in a text box, as well as provide a description. Show a little leaderboard that will show the highest performing to lowest performing tools by averaging those scores."
+    gaia-code "Build me an AI tool rater in nextjs where I can give the name of the AI programming tool, give it a score out of 10 for speed and quality in a text box, as well as provide a description. Show a little leaderboard that will show the highest performing to lowest performing tools by averaging those scores."
     ```
   </Tab>
 
   <Tab title="Simple Todos">
     ```bash
-    gaia code "Build me a todo tracking app using typescript"
+    gaia-code "Build me a todo tracking app using typescript"
     ```
   </Tab>
 
   <Tab title="Interactive Mode">
     ```bash
-    gaia code --interactive
+    gaia-code --interactive
     # then type your prompt when prompted
     ```
   </Tab>
@@ -172,21 +172,21 @@ your-app/
 <CardGroup cols={2}>
   <Card title="Debug Logging" icon="bug">
     ```bash
-    gaia code "Create a todo tracking app in nextjs" --debug
+    gaia-code "Create a todo tracking app in nextjs" --debug
     ```
     See internal decision logs
   </Card>
 
   <Card title="JSON Trace" icon="file-code">
     ```bash
-    gaia code "Create a todo tracking app in nextjs" --trace
+    gaia-code "Create a todo tracking app in nextjs" --trace
     ```
     Save detailed execution trace
   </Card>
 
   <Card title="Full Debug" icon="magnifying-glass-chart">
     ```bash
-    gaia code "Create a todo tracking app in nextjs" --debug --trace
+    gaia-code "Create a todo tracking app in nextjs" --debug --trace
     ```
     Maximum debugging information
   </Card>

docs/guides/routing.mdx

@@ -28,7 +28,7 @@ The routing agent solves these problems by:
 - Separating routing concerns from agent logic
 - Using LLM-powered analysis to detect language/framework from natural language
 - Asking users for clarification when uncertain, rather than guessing
-- Providing a consistent routing experience across all agents (currently used for `gaia code`, with plans to expand)
+- Providing a consistent routing experience across all agents (currently used for `gaia-code`, with plans to expand)
 
 ## How It Works
 
@@ -63,11 +63,11 @@ The routing agent is automatically used when you run certain GAIA commands:
 
 ```bash
 # Routing happens automatically
-gaia code "Create a REST API with Express and SQLite"
+gaia-code "Create a REST API with Express and SQLite"
 # → Detected: TypeScript backend → Creates TypeScript CodeAgent
 
 # If ambiguous, you'll be prompted
-gaia code "Create a todo backend app"
+gaia-code "Create a todo backend app"
 # → What language/framework would you like to use for your backend project?
 # → (e.g., 'Express', 'Django', 'React', 'FastAPI')
 # User: Express
@@ -115,7 +115,7 @@ The routing agent uses the following rules for language detection:
 ### High-Confidence Detection (No Questions)
 
 ```bash
-$ gaia code "Create an Express API with SQLite"
+$ gaia-code "Create an Express API with SQLite"
 [2025-11-18 10:08:03] | INFO | Analysis result: {
     'language': 'typescript',
     'project_type': 'backend',
@@ -127,7 +127,7 @@ $ gaia code "Create an Express API with SQLite"
 ### Conversational Disambiguation
 
 ```bash
-$ gaia code "Build me a todo backend app"
+$ gaia-code "Build me a todo backend app"
 
 What language/framework would you like to use for your backend project?
 (e.g., 'Express', 'Django', 'React', 'FastAPI')
@@ -145,7 +145,7 @@ What language/framework would you like to use for your backend project?
 ### Multiple Disambiguation Rounds
 
 ```bash
-$ gaia code "Create an app"
+$ gaia-code "Create an app"
 
 What kind of application would you like to build?
 (e.g., 'React web app', 'Python CLI tool', 'Express API', 'Django backend')
@@ -176,7 +176,7 @@ Add these to your `.env` file for persistent configuration.
 
 The routing agent is currently integrated with:
 
-- **`gaia code`**: Intelligently routes to Python or TypeScript CodeAgent based on framework detection
+- **`gaia-code`**: Intelligently routes to Python or TypeScript CodeAgent based on framework detection
 
 **Future Integration Plans:**
 - `gaia docker`: Route to appropriate containerization strategy
@@ -217,7 +217,7 @@ echo $AGENT_ROUTING_MODEL
 echo $LEMONADE_BASE_URL
 
 # Test with a clear request
-gaia code "Create an Express API with SQLite"
+gaia-code "Create an Express API with SQLite"
 ```
 
 ### Low Confidence / Always Asks Questions

docs/playbooks/code-agent/part-1-introduction.mdx

@@ -52,7 +52,7 @@ Building modern web applications requires:
 ### Example
 
 ```bash
-gaia code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10"
+gaia-code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10"
 ```
 
 **Result:** A complete Next.js app with:
@@ -151,7 +151,7 @@ GAIA Code uses a **Minimum Viable Product (MVP) approach** when generating appli
 <Tabs>
   <Tab title="Initial Prompt">
     ```bash
-    gaia code "Build me a movie tracking app"
+    gaia-code "Build me a movie tracking app"
     ```
   </Tab>
 
@@ -175,7 +175,7 @@ GAIA Code uses a **Minimum Viable Product (MVP) approach** when generating appli
 <Tabs>
   <Tab title="Specific Prompt">
     ```bash
-    gaia code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10"
+    gaia-code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10"
     ```
   </Tab>
 
@@ -261,11 +261,11 @@ The agent doesn't overengineer. It creates the minimum viable product based on y
 
 ```bash
 # Simple prompt = minimal schema
-gaia code "Build me a workout tracker"
+gaia-code "Build me a workout tracker"
 # Likely generates: workout name, date, completed
 
 # Detailed prompt = detailed schema
-gaia code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"
+gaia-code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"
 # Generates exactly what you specified
 ```
 
@@ -313,7 +313,7 @@ Let's see GAIA Code in action:
 
   <Step title="Generate an app">
     ```bash
-    gaia code "Build me a todo tracking app using typescript"
+    gaia-code "Build me a todo tracking app using typescript"
     ```
   </Step>
 

docs/playbooks/code-agent/part-2-app-creation.mdx

@@ -26,7 +26,7 @@ Let's walk through creating a movie tracking app to understand each component.
 ### The Prompt
 
 ```bash
-gaia code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10"
+gaia-code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10"
 ```
 
 This single command triggers a complete generation pipeline.
@@ -573,31 +573,31 @@ Here are verified prompts that generate complete applications:
 ### Movie Tracking App
 
 ```bash
-gaia code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10"
+gaia-code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10"
 ```
 
 ### Workout Tracking App
 
 ```bash
-gaia code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"
+gaia-code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"
 ```
 
 ### Restaurant Rating App
 
 ```bash
-gaia code "Build me a restaurant rating application. I want to be able to put the location of the restaurant, the food that I ate, and my review"
+gaia-code "Build me a restaurant rating application. I want to be able to put the location of the restaurant, the food that I ate, and my review"
 ```
 
 ### AI Tool Rating with Leaderboard
 
 ```bash
-gaia code "Build me an AI tool rating algorithm in nextjs where I can give the name of the AI programming tool, give it a score out of 10 for speed and quality in a text box, as well as provide a description. Show a little leaderboard that will show the highest performing to lowest performing tools by averaging those scores"
+gaia-code "Build me an AI tool rating algorithm in nextjs where I can give the name of the AI programming tool, give it a score out of 10 for speed and quality in a text box, as well as provide a description. Show a little leaderboard that will show the highest performing to lowest performing tools by averaging those scores"
 ```
 
 ### Simple Todo Tracker
 
 ```bash
-gaia code "Build me a todo tracking app using typescript"
+gaia-code "Build me a todo tracking app using typescript"
 ```
 
 ---

docs/playbooks/code-agent/part-3-validation-building.mdx

@@ -508,7 +508,7 @@ From prompt to working app:
 
 ```bash
 # 1. Generate
-gaia code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"
+gaia-code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"
 
 # 2. Run
 cd workout-tracking-app

docs/reference/cli.mdx

@@ -242,31 +242,31 @@ lemonade-server serve --ctx-size 32768
 Routing detects "Express" and uses TypeScript:
 <CodeGroup>
 ```bash TypeScript/Express
-gaia code "Create a REST API with Express and SQLite for managing products"
+gaia-code "Create a REST API with Express and SQLite for managing products"
 ```
 </CodeGroup>
 
 Routing detects "Django" and uses Python:
 <CodeGroup>
 ```bash Python/Django
-gaia code "Create a Django REST API with authentication"
+gaia-code "Create a Django REST API with authentication"
 ```
 </CodeGroup>
 
 Routing detects "React" and uses TypeScript frontend:
 <CodeGroup>
 ```bash React Frontend
-gaia code "Create a React dashboard with user management"
+gaia-code "Create a React dashboard with user management"
 ```
 </CodeGroup>
 
 <CodeGroup>
 ```bash Interactive Mode
-gaia code --interactive
+gaia-code --interactive
 ```
 
 ```bash Cloud LLM
-gaia code "Create a REST API" --use-claude
+gaia-code "Create a REST API" --use-claude
 ```
 </CodeGroup>
 

setup.py

@@ -170,6 +170,7 @@
             "gaia-mcp = gaia.mcp.mcp_bridge:main",
             "gaia-mcp-atlassian = gaia.mcp.atlassian_mcp:main",
             "gaia-emr = gaia.agents.emr.cli:main",
+            "gaia-code = gaia.agents.code.cli:main",
         ]
     },
     python_requires=">=3.10",