Better CLI Page (#1249)

# Motivation

<!-- Why is this change necessary? -->

# Content

<!-- Please include a summary of the change -->

# Testing

<!-- How was the change tested? -->

# Please check the following before marking your PR as ready for review

- [ ] I have added tests for my changes
- [ ] I have updated the documentation or added new documentation as
needed

Author: jayhack

docs/api-reference/overview.mdx

@@ -107,7 +107,7 @@ curl -X POST "https://api.codegen.com/v1/organizations/{org_id}/agent/run/resume
 
 <Card
   title="Programmatically Retrieve Agent Traces"
-  icon="scroll-text"
+  icon="list"
   href="/api-reference/agent-run-logs"
 >
   Learn how to retrieve and analyze detailed agent execution logs.

docs/introduction/cli.mdx

@@ -5,7 +5,7 @@ icon: "terminal"
 iconType: "solid"
 ---
 
-The `codegen` CLI allows users to run and interact with agents from the terminal.
+The `codegen` CLI is your terminal interface to Codegen agents. Use it to view agents, pull their work, create new agents, and run Claude Code with full telemetry and monitoring.
 
 <iframe
   className="w-full aspect-video rounded-xl"
@@ -16,126 +16,48 @@ The `codegen` CLI allows users to run and interact with agents from the terminal
   allowFullScreen
 ></iframe>
 
-## Installation
+## Installation & Setup
 
 ```bash
 uv tool install codegen
 ```
 
-## Initialization
+The CLI uses your API token for authentication. Get your token and organization ID from the **[authentication guide](/api-reference/authentication)**.
 
 ```bash
 codegen login
 ```
 
-## CLI Reference
+## Key Commands
 
-### `codegen` (root)
+### `codegen`
 
-**Description:** Launches the interactive TUI if no subcommand is provided.
-
----
-
-### `codegen agent`
-
-**Description:** Create a new agent run with a prompt, fetch an existing agent run by ID, or pull PR branch.
-
-**Usage Patterns:**
-
-- **Create run:** `codegen agent --prompt "Your prompt"`
-- **Get run JSON:** `codegen agent --id 123 --json`
-- **Pull PR branch:** `codegen agent --id 123 pull`
-
-**Options:**
-
-- `--prompt, -p TEXT` The prompt to send to the agent (mutually exclusive with --id unless using create)
-- `--id INT` Agent run ID to fetch or pull
-- `--json` Output raw JSON response when fetching (flag)
-- `--org-id INT` Organization ID (defaults to CODEGEN_API_TOKEN/REPOSITORY_ORG_ID or auto-detect)
-- `--model TEXT` Model to use for this agent run (optional)
-- `--repo-id INT` Repository ID to use for this agent run (optional)
-
-**Positional Actions:**
-
-- `pull` Pull the PR branch associated with an agent run (requires --id)
-
----
-
-### `codegen agents`
-
-**Description:** List and manage agent runs.
-
-**Usage Patterns:**
-
-- **List runs:** `codegen agents list`
-- **Get run details:** `codegen agents get 123`
-
-**Options:**
-
-- `--org-id INT` Organization ID (defaults to CODEGEN_ORG_ID/REPOSITORY_ORG_ID or auto-detect)
-- `--limit INT` Maximum number of runs to return (default: 10)
-- `--json` Output raw JSON response (flag)
-
----
+Launches the interactive terminal UI (TUI) for browsing agents, viewing runs, and managing your Codegen workflow from the terminal.
 
 ### `codegen login`
 
-**Description:** Store authentication token.
-
-**Usage Patterns:**
-
-- **Interactive login:** `codegen login`
-- **Token login:** `codegen login --token YOUR_API_TOKEN`
-
-**Options:**
+Store your API token for authentication. Supports both interactive login and direct token input.
 
-- `--token TEXT` API token to store
-- `--no-verify` Skip token verification (flag)
-
----
-
-### `codegen logout`
-
-**Description:** Clear stored authentication token.
-
-**Usage Pattern:**
-
-- `codegen logout`
-
----
-
-### `codegen org`
-
-**Description:** Manage and switch between organizations.
-
-**Usage Patterns:**
-
-- **List organizations:** `codegen org list`
-- **Switch organization:** `codegen org switch ORG_ID`
-- **Get current organization:** `codegen org current`
-
-**Options:**
-
-- `--json` Output raw JSON response (flag)
-
----
-
-### `codegen repo`
-
-**Description:** Manage repository configuration and environment variables.
-
-**Usage Patterns:**
+```bash
+# Interactive login
+codegen login
 
-- **List repositories:** `codegen repo list`
-- **Configure repository:** `codegen repo config REPO_NAME`
-- **Get repository details:** `codegen repo get REPO_ID`
+# Direct token login
+codegen login --token YOUR_API_TOKEN
+```
 
-**Options:**
+## What You Can Do
 
-- `--org-id INT` Organization ID (defaults to CODEGEN_ORG_ID or auto-detect)
-- `--json` Output raw JSON response (flag)
+- **View and manage agents** - List agent runs, check status, and see detailed execution logs
+- **Pull agent work** - Download branches and code changes created by agents directly to your local environment
+- **Create new agents** - Trigger agent runs from the command line with custom prompts
+- **Run Claude Code** - Execute Claude Code with OpenTelemetry monitoring and comprehensive logging
+- **Manage organizations** - Switch between organizations and configure repositories
 
----
+<Note>
+  The CLI provides the same capabilities as the web UI and API, optimized for
+  terminal-based workflows and automation.
+</Note>
 
 ## Get Started