Command Line Interface

The Deep Agent CLI provides an interactive terminal interface for working with AI agents directly from your command line. Built with Ink (React for CLI), it offers a rich, visual experience with real-time streaming, event rendering, and interactive workflows.

What is the CLI?

The Deep Agent CLI is a terminal-based interactive agent that combines:

When to Use the CLI

The CLI is ideal for:

• Development workflows - Code generation, refactoring, debugging assistance
• File operations - Batch file processing, codebase navigation, project setup
• Research tasks - Web searches, API calls, content fetching and summarization
• Scripting - Execute shell commands, run tests, manage dependencies
• Learning - Explore agent behavior and capabilities interactively
• Quick prototyping - Test prompts and agent configurations without writing code

CLI vs. Programmatic Usage

Installation

Prerequisites

# Install Bun
curl -fsSL https://bun.sh/install | bash

Installation Options

bunx ai-sdk-deep-agent

bun add -g ai-sdk-deep-agent
deep-agent

cd your-project
bun add ai-sdk-deep-agent
bunx deep-agent

git clone https://github.com/chrispangg/ai-sdk-deepagent.git
cd ai-sdk-deepagent
bun install
bun run cli

Quick Start

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...              # Optional
TAVILY_API_KEY=tvly-...            # Optional, for web_search tool

export ANTHROPIC_API_KEY=sk-ant-...
export TAVILY_API_KEY=tvly-...     # For web search capabilities

bunx ai-sdk-deep-agent

>_ Deep Agent
model:     anthropic/claude-haiku-4-5-20251001  /model to change
directory: ~/my-project

To get started, describe a task or try one of these commands:

/help - show available commands
/features - show enabled features
/model - change the model

> Create a TypeScript function that sorts an array

Features Overview

Natural Language Interaction

Chat with the agent to accomplish tasks:

> Refactor this function to use async/await
> Write unit tests for the User model
> Explain how this code works

Real-Time Streaming

Watch responses stream in real-time with status indicators:

● I'll help you refactor that function.▌

Event Visualization

See tool calls, file operations, and subagents execute live:

─── step 1 ───
📁 ls: 23 files found
📄 read_file: src/index.ts (150 lines)
✏️ edit_file: src/index.ts (3 occurrences)
📋 Todos: 1/3 completed

Tool Approval Workflow

🛑 Tool Approval Required
Tool: execute
Arguments:
{
  "command": "rm -rf node_modules"
}

Press [Y] to approve, [N] to deny, [A] to approve all (enable auto-approve)

Session Persistence

Save and resume conversations:

# Start a new session
bunx ai-sdk-deep-agent --session my-project

# Later, resume the session
bunx ai-sdk-deep-agent --session my-project

Performance Features

Built-in optimizations for long-running conversations:

• Prompt Caching - Cache system prompts for faster subsequent calls (Anthropic only)
• Tool Result Eviction - Automatically evict large tool results to prevent context overflow
• Auto-Summarization - Summarize older messages when approaching token limits

Web Tools

• web_search - Powered by Tavily API
• http_request - Make HTTP requests to any API
• fetch_url - Fetch web pages and convert HTML to Markdown

Built-in Tools

The CLI includes all Deep Agent tools:

Planning

• write_todos - Manage task lists for complex operations

Filesystem

• ls - List files in a directory
• read_file - Read file contents with line numbers
• write_file - Create a new file
• edit_file - Replace text in an existing file
• glob - Find files matching a pattern
• grep - Search for text within files

Web (requires TAVILY_API_KEY)

• web_search - Search the web using Tavily API
• http_request - Make HTTP requests to APIs
• fetch_url - Fetch web pages and convert to Markdown

Shell Command Execution

• execute - Execute shell commands in the working directory

Subagent Spawning

• task - Delegate work to specialized subagents

Architecture

The CLI is built with:

• Ink - React for CLI, providing a component-based architecture
• React hooks - useAgent hook manages agent state and streaming
• Event-driven - Real-time event rendering for all agent activities
• TypeScript - Full type safety and IDE support

Key Components

• App (src/cli/index.tsx) - Main application component
• useAgent hook (src/cli/hooks/useAgent.ts) - Agent state management
• Components (src/cli/components/) - Reusable UI components
• Theme (src/cli/theme.ts) - Colors, styling, and slash commands

Next Steps

Troubleshooting

For more help, see GitHub Issues.