Skip to main content
The PandaAGI CLI provides a powerful terminal-based interface for interacting with agents, perfect for developers who prefer command-line tools or need to integrate agents into scripts and automation workflows.
PandaAGI CLI Interface showing real-time agent interactions in the terminal

PandaAGI CLI Interface

​
Why Use the CLI?

Developer-Friendly

Perfect for developers who prefer working in the terminal or need to integrate with scripts and automation workflows.

Lightweight

Minimal resource usage with the same powerful agent capabilities as the web interface.

Real-Time Feedback

Watch the agent’s thinking process, actions, and results in real-time with rich visual feedback.

Session Persistence

Resume conversations and keep context across multiple sessions with conversation IDs.

​
Quick Start

1

Install Dependencies

Ensure you have Python 3.9+ and the PandaAGI SDK installed:
poetry add panda_agi rich
The CLI requires the rich library for enhanced terminal output.
2

Set Your API Key

Set your PandaAGI API key as an environment variable:
export PANDA_AGI_KEY="your-api-key"
You can add this to your shell profile for persistence.
3

Run the CLI

Start the CLI with default settings:
poetry run python examples/cli.py
This creates a workspace in ./my_agent_workspace and starts an interactive session.
4

Start Interacting

Type your message and press Enter to send it to the agent. You’ll see the agent’s thinking process, actions, and responses in real-time.
Type help to see all available CLI commands.

​
Key Features

Watch the agent’s thinking process, actions, and responses as they happen with color-coded event types and timestamps.
# Event streaming is built into the CLI
async for event in agent.run_stream(query):
    # Process events in real-time
    if isinstance(event, BaseStreamEvent):
        event_type = event.type.value if hasattr(event.type, "value") else str(event.type)
        
        # Apply appropriate styling based on event type
        style_info = get_event_style(event_type)
        
        # Render the event with appropriate colors and icons
        render_event(event, style_info)
        
        # Update session statistics
        update_session_stats(event_type)
The CLI maintains conversation history within a session and allows you to resume conversations using conversation IDs.
# Resume a previous conversation
poetry run python examples/cli.py --conversation-id "123e4567-e89b-12d3-a456-426614174000"
This is particularly useful for long-running tasks or when you need to continue work across different sessions.
The CLI supports special commands to control the session:
  • help - Show available commands
  • clear - Clear the screen
  • exit, quit, or q - Exit the CLI
  • stats - Show detailed session statistics
  • status - Show current status and statistics
  • history - Show event history summary
  • reset - Reset session statistics
The CLI uses the rich library to provide enhanced visual feedback:
  • Color-coded event categories (system, user, web, file, shell, image)
  • Custom icons for different event types (🔗, 💬, 🔍, 📖, 💻, 🎨)
  • Progress bars for long-running operations
  • Syntax highlighting for code snippets
  • Panels with rounded or heavy borders for visual organization
  • Comprehensive session statistics and event history tracking

​
Command Line Options

python examples/cli.py [OPTIONS]

  • Options Reference
  • Environment Setup
OptionShortDescriptionDefault
--workspace-wPath to agent workspace directory./my_agent_workspace
--conversation-idResume an existing conversation by IDNone
--no-timestampsDisable timestamp display in eventsFalse
--widthPanel width in characters120
--compact-cUse compact display mode for better performanceFalse
--verbose-vShow additional debug information and full tracebacksFalse

​
Visual Event Categories

System Events

  • 🔗 Connection Established
  • 🎯 Task Completed
  • ⚙️ System Operations

User Interaction

  • 💬 User Notification
  • ❓ User Question
  • 👤 User Input

Web Operations

  • 🔍 Web Search
  • 📊 Web Search Results
  • 🌐 Web Navigation
  • 📄 Web Page Content

File Operations

  • 📖 File Read
  • ✏️ File Write
  • 🔄 File Replace
  • 🔎 File Find
  • 📁 File Explore

Shell Operations

  • 💻 Shell Execute
  • 👁️ Shell View
  • ⌨️ Shell Write

AI Operations

  • 🤖 Agent Actions
  • 🎨 Image Generation
  • 🧠 Thinking Process

​
Advanced Usage

​
Session Statistics

The CLI automatically tracks and can display comprehensive session statistics using the stats command: 
┌─────────────── Detailed Session Statistics ───────────────┐
│ Metric                 │ Value                            │
│ Session Runtime        │ 00:15:32                         │
│ Total Events           │ 127                              │
│ User Messages          │ 8                                │
│ Agent Operations       │ 119                              │
│ Errors Encountered     │ 2                                │
│ Events/Minute          │ 8.2                              │
└─────────────────────────────────────────────────────────┘

Example Session Statistics

You can also view a summary of events by category using the history command: 
┌─────────────── Event History Summary ───────────────┐
│ Category    │ Count │ Icon                          │
│ System      │ 5     │ ⚙️                            │
│ User        │ 8     │ 👤                            │
│ Web         │ 42    │ 🌐                            │
│ File        │ 23    │ 📁                            │
│ Shell       │ 37    │ 💻                            │
│ Image       │ 12    │ 🎨                            │
└─────────────────────────────────────────────────────┘

Event History Summary

​
Workspace Management

1

Default Workspace

The CLI automatically creates and manages a workspace directory at ./my_agent_workspace unless specified otherwise. This workspace is where the agent stores files and other artifacts it creates during operation.
2

Custom Workspace

You can specify a custom workspace directory:
poetry run python examples/cli.py -w ./my_custom_workspace
This is useful when working on different projects or when you want to isolate agent workspaces.
3

Persistent Conversations

The CLI supports resuming conversations across sessions using the conversation ID:
# First session - note the conversation ID in the output
poetry run python examples/cli.py

# Later session - resume with the same conversation ID
poetry run python examples/cli.py --conversation-id "123e4567-e89b-12d3-a456-426614174000"
This allows for long-running tasks to be continued even after closing the terminal.

​
Workspace Contents

The workspace directory contains all artifacts created during agent operations:
  • Files created or modified by the agent
  • Downloaded web content and search results
  • Generated images and other media
  • Temporary files and execution artifacts
  • Conversation history and context data

​
Next Steps

Quickstart Guide

Return to the quickstart guide to explore more capabilities

Chat Interface

Try the web-based chat interface for a graphical experience

Event System

Dive deeper into the event system that powers both the CLI and chat interfaces
⌘I