ChatGPT CLI

ChatGPT CLI is a powerful, multi-provider command-line interface for working with modern LLMs. It supports OpenAI, Azure, Perplexity, LLaMA, and more, and includes streaming, interactive chat, prompt files, image/audio I/O, MCP tool calls, and an agent mode for multi-step tasks with safety and budget controls.

Features

Streaming and Query Modes

• Streaming mode: Real-time interaction with the GPT model
• Query mode: Single input-output interactions
• Interactive mode: Conversational experience with token usage tracking

Thread-Based Context Management

Seamless conversations with individualized context for each thread. Each unique thread has its own history, ensuring relevant and coherent responses across different chat instances.

# Work on different projects
chatgpt --thread backend "explain this API"
chatgpt --thread frontend "review this React component"

Sliding Window History

History automatically trims to stay within token limits while preserving context. Window size adjustable through the context-window setting.

Custom Context from Any Source

Pipe context from files, stdin, or any program:

# Analyze log files
tail -f app.log | chatgpt "summarize errors"

# Review code
cat main.go | chatgpt "suggest improvements"

# Process images
pngpaste - | chatgpt "What is this photo?"

Agent Mode (ReAct + Plan/Execute)

Run multi-step tasks that can think, act, and observe using tools like shell, file operations, and LLM reasoning. Supports both iterative ReAct loops and Plan/Execute workflows, with built-in budget limits and policy enforcement for safe-by-default automation.

Two Agent Strategies

ReAct Mode - Iterative "think → act → observe" loop:

chatgpt "why is my test failing?" --agent

Plan/Execute Mode - Generates a plan first, then executes step-by-step:

chatgpt "what is the weather like in brooklyn" --agent --agent-mode plan

Workdir Safety

Agent file access can be restricted to a working directory:

chatgpt "what files are in the /tmp directory" \
  --agent \
  --agent-work-dir .

Budgets and Policy

Agent execution is governed by:

• Budget limits: iterations, steps, tool calls, wall-time, token usage
• Policy rules: allowed tools, denied shell commands, file op allowlist, workdir path restrictions

Logs

Detailed execution logs automatically written to $OPENAI_CACHE_HOME/agent/. Each run gets its own timestamped log directory with:

• Planner output (Plan/Execute mode)
• Tool calls and results
• Timing and budget usage
• Debug traces

Web Search

Allow compatible models (e.g. gpt-5+) to fetch live web data during queries:

chatgpt "latest AI developments" --web --web-context-size high

MCP (Model Context Protocol) Support

Call external MCP tools via HTTP(S) or STDIO, inject results into conversation context, and continue seamlessly.

HTTP example:

chatgpt \
  --mcp "https://mcp.apify.com/?tools=epctex/weather-scraper" \
  --mcp-tool "epctex-slash-weather-scraper" \
  --mcp-header "Authorization: Bearer $APIFY_API_KEY" \
  --mcp-param locations='["Brooklyn, NY"]' \
  "what should I wear today"

STDIO example:

chatgpt \
  --mcp "stdio:python test/mcp/stdio/mcp_stdio_server.py" \
  --mcp-tool echo \
  --mcp-param 'payload={"foo":"bar"}' \
  "What did the MCP server receive?"

MCP sessions are automatically initialized and managed.

Image Support

• Upload images or provide URLs using --image
• Generate images with --draw and --output
• Edit images with --draw, --image, and --output (e.g., "add sunglasses to the cat")

chatgpt --image photo.jpg "describe this image"
chatgpt --draw "sunset over brooklyn bridge" --output sunset.png
chatgpt --draw --image cat.jpg --output cat-cool.jpg "add sunglasses"

Audio Support

• Upload audio files with --audio (MP3/WAV)
• Transcribe audio with --transcribe (supports MP3, MP4, MPEG, MPGA, M4A, WAV, WEBM)
• Text-to-speech with --speak and --output

chatgpt --audio meeting.mp3 "summarize this meeting"
chatgpt --transcribe interview.wav
chatgpt --speak "convert this to audio" --output speech.mp3

Prompt Support

Provide rich context from files with --prompt:

git diff | chatgpt --prompt prompts/write_pull-request.md

Check out the awesome prompts repository for ready-to-use examples.

Model Listing

Access available models with -l or --list-models:

chatgpt --list-models

Advanced Configuration

• Layered configuration: defaults, config.yaml, environment variables, command-line flags
• Multiple provider configs with --target flag
• Quick adjustments with --set- flags
• View current settings with --config

Installation

Homebrew (macOS)

brew tap kardolus/chatgpt-cli && brew install chatgpt-cli

Direct Download

Pre-built binaries available for:

• macOS (Apple Silicon & Intel)
• Linux (amd64, arm64, 386)
• FreeBSD (amd64, arm64)
• Windows (amd64)

Download from GitHub Releases

Getting Started

1. Set your API key:

export OPENAI_API_KEY="your_api_key"

2. Create history directory (optional, enables context tracking):

mkdir -p ~/.chatgpt-cli

3. Try it:

chatgpt "what is the capital of the Netherlands"

4. Interactive mode:

chatgpt --interactive

Configuration

Switching Between Providers

Use --target to switch between provider configurations:

~/.chatgpt-cli/
├── config.yaml           # Default (OpenAI)
├── config.azure.yaml     # Azure setup
├── config.perplexity.yaml # Perplexity setup
└── config.llama.yaml     # LLaMA setup

chatgpt --target azure "hello"

Azure Configuration

name: azure
api_key: <key>
url: https://<resource>.openai.azure.com
completions_path: /openai/deployments/<deployment>/chat/completions?api-version=<version>
auth_header: api-key
auth_token_prefix: ""

Perplexity Configuration

name: perplexity
api_key: <key>
model: sonar
url: https://api.perplexity.ai

Quick Config Changes

chatgpt --set-model gpt-4o
chatgpt --set-thread backend-work
chatgpt --config  # View current config

Useful Links

• GitHub: https://github.com/kardolus/chatgpt-cli
• Documentation: Full README with examples
• Prompts Repository: https://github.com/kardolus/prompts
• Issues & Discussion: GitHub Issues and Discussions
• MIT License

Why ChatGPT CLI?

Built by developers, for developers. ChatGPT CLI brings the power of modern LLMs directly to your terminal—where you already work. No context switching, no web UI, just command-line efficiency with the safety and flexibility needed for real-world automation.