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

​
Command Line Options

python examples/cli.py [OPTIONS]

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