SuperCharged-Claude-Code-Upgrade/dexto/packages/cli/CLI.md

Dexto CLI Documentation

The Dexto CLI provides an interactive terminal interface for conversing with AI agents, managing sessions, switching models, and executing commands.

Quick Start

# Start web UI (default)
dexto

# Start interactive CLI
dexto --mode cli

# Run one-shot query
dexto "what is the current time"

# Run with specific agent
dexto --agent coding-agent --mode cli

CLI Features

Interactive Chat

• Modern Terminal UI - Built with Ink for a responsive, chat-optimized interface
• Real-time Streaming - See AI responses as they're generated
• Message History - Scroll through conversation with up/down arrows
• Auto-complete - Slash commands and resource mentions with tab completion

Slash Commands

Type / to see available commands:

• /help - Show available commands
• /model - Switch LLM model (interactive selector)
• /session - Manage chat sessions
  • /session list - List all sessions
  • /session switch - Switch to another session (interactive)
  • /session new - Create new session
  • /session delete <id> - Delete a session
• /clear - Clear conversation history
• /exit or /quit - Exit the CLI

Resource References

Use @ to reference files and resources:

• Type @ at the start of input or after a space
• Autocomplete shows available resources from MCP servers
• Select with arrow keys and Enter

Session Management

• New session: Each CLI launch starts fresh (first message creates new session)
• Resume by ID: dexto --mode cli -r <session-id> (resume specific session)
• Resume interactively: Use /resume or /session switch in CLI
• Auto-save: Sessions are automatically saved
• Search history: dexto search <query>

Model Switching

# Switch model via command
dexto -m gpt-4o --mode cli

# Or use interactive selector in CLI
/model

Keyboard Shortcuts

• ↑/↓ - Navigate input history
• Esc - Cancel current operation or close overlays
• Ctrl+C - Exit CLI (or cancel if processing)
• Tab - Autocomplete commands/resources
• Enter - Submit input or select autocomplete item

Advanced Usage

Tool Confirmation

# Auto-approve all tool executions
dexto --mode cli --auto-approve

# Manual approval (default)
dexto --mode cli

Custom Agents

# Use agent by name
dexto --agent coding-agent --mode cli

# Use agent from file
dexto --agent ./my-agent.yml --mode cli

Headless Mode

# One-shot query with output
dexto -p "list files in current directory"

# Resume a session and run query
dexto -r <session-id> -p "what did we discuss?"

# Piped input
cat document.txt | dexto -p "summarize this"

Architecture

The CLI is built on a modern, maintainable architecture:

Core Components

• InkCLIRefactored - Main orchestrator using React Ink
• State Management - Centralized reducer pattern for predictable state
• Custom Hooks - Reusable logic (events, history, shortcuts, overlays)
• Services - Business logic layer (commands, messages, input parsing)
• Base Components - Reusable UI primitives (selectors, autocomplete)

Code Structure

packages/cli/src/cli/ink-cli/
├── InkCLIRefactored.tsx       # Main component
├── state/                      # State management
├── hooks/                      # Custom hooks
├── services/                   # Business logic
├── components/                 # UI components
│   ├── base/                   # Reusable components
│   ├── chat/                   # Chat UI
│   ├── input/                  # Input area
│   └── overlays/               # Model/session selectors
├── containers/                 # Smart containers
└── utils/                      # Helper functions

Troubleshooting

CLI Not Starting

• Ensure terminal supports UTF-8 and ANSI colors
• Try setting TERM=xterm-256color
• Check that Node.js >= 20.0.0

Autocomplete Not Working

• Make sure you're in interactive mode (not headless)
• Type / for commands or @ for resources
• Arrow keys to navigate, Tab to load into input, Enter to select

Session Not Found

• List sessions: dexto session list
• Sessions are stored in ~/.dexto/sessions/ (or repo .dexto/ in dev mode)
• Use session ID from list output

Model Not Available

• Check configured providers in agent config
• Ensure API keys are set in environment or .env
• Use /model to see available models

Development

Dev Mode

# Use repository configs (not global ~/.dexto)
export DEXTO_DEV_MODE=true
dexto --mode cli

Hot Reload

# Build and run dev server
pnpm run dev

# Or just CLI
pnpm run build:cli
dexto --mode cli

Testing

# Unit tests
pnpm run test:unit

# Integration tests
pnpm run test:integ

# All tests
pnpm test

See Also

• Main README - Project overview
• Development Guide - Development workflows
• Agent Configuration - Default agent setup
• Core Documentation - Core library reference