Agent CLI Tool
A powerful command-line tool for interacting with AI models (OpenAI, DeepSeek, Claude) directly from your terminal. Features a plugin-based architecture, multiple UI modes, and extensible hook system.
Features
- Three UI Modes:
stdout- Plain text with ANSI colorsrich- Live markdown rendering with syntax highlightingtui- Full interactive terminal UI with session management
- AI Modes:
default- General purpose conversationsshell- Generate shell commands onlycode- Generate code only
- Plugin System - Hook-based architecture for extending functionality
- Built-in Plugins:
@file("path")- Inject file content into prompts@fetch("url")- Fetch and inject web content- Shell command execution confirmation
- Multi-modal Input - Command-line args, pipe, or interactive TTY
- Session Management (TUI mode) - History browsing and persistence
Installation
Using pip
pip install agent-cli-tool
Using uv
uv tool install agent-cli-tool
From source
git clone https://github.com/Awoodwhale/agent-cli-tool.git
cd agent-cli-tool
uv pip install -e .
Configuration
Create a configuration file at ~/.config/agent-cli-tool/.env:
# Required
API_KEY=your_api_key
BASE_URL=https://api.openai.com/v1
DEFAULT_MODEL=deepseek-chat
# Optional
UI_MODE=stdout # stdout | rich | tui
DEFAULT_LANGUAGE=python3 # Default language for code mode
RICH_STYLE=github-dark # Pygments style for rich mode
STREAM=true # Enable streaming
TIMEOUT=60 # Request timeout in seconds
# Custom prompts
DEFAULT_PROMPT=You are a helpful assistant
SHELL_PROMPT=Provide only shell commands...
CODE_PROMPT=Provide only code...
# UI customization (for stdout/rich modes)
USER_EMOJI=👤
AI_EMOJI=🤖
THINK_START_EMOJI=🤔 [Thinking]
THINK_END_EMOJI=💡 [Done]
Usage
Basic Query
agent-cli-tool "Explain quantum computing"
UI Modes
# Plain text output (default)
agent-cli-tool "What is AI?"
# Markdown rendering
agent-cli-tool --ui-mode rich "Explain machine learning"
# Interactive TUI with session management
agent-cli-tool --ui-mode tui
AI Modes
# Shell mode - generates shell commands only
agent-cli-tool --shell "list all python processes"
# Code mode - generates code only
agent-cli-tool --code "fibonacci function in python"
Conversation Mode
# Multi-turn conversation
agent-cli-tool --conversation
# or
agent-cli-tool -c
Model Selection
agent-cli-tool -m GPT-5 "Explain quantum computing" # GPT-5
agent-cli-tool -m deepseek-r1 "Solve this math problem" # DeepSeek Reasoner
agent-cli-tool -m "claude sonnet 4.5" "Write a poem" # claude sonnet 4.5
Output to File
agent-cli-tool --code "web scraper in python" --output scraper.py
Using Plugins
# Inject file content
agent-cli-tool 'Review this code: @file("src/main.py")'
# Fetch web content
agent-cli-tool 'Summarize: @fetch("https://example.com/article")'
Pipe Input
echo "explain this error" | agent-cli-tool
cat error.log | agent-cli-tool "what went wrong?"
Command Line Options
usage: agent-cli-tool [-h] [-m MODEL] [-a] [-iu] [-ia] [-it] [-c] [-sh] [-co] [-o OUTPUT] [-u {stdout,rich,tui}] [prompt]
positional arguments:
prompt User input prompt
options:
-h, --help Show help message
-m, --model MODEL AI model to use
-a, --ahead Place arg prompt before pipe prompt (default: true)
-iu, --ignore_user Don't display user input
-ia, --ignore_ai Don't display AI model info
-it, --ignore_think Don't display AI thinking/reasoning content
-c, --conversation Enable multi-turn conversation mode
-sh, --shell Shell mode - output shell commands only
-co, --code Code mode - output code only
-o, --output OUTPUT Write output to file
-u, --ui-mode {stdout,rich,tui}
UI rendering mode
TUI Mode
The TUI mode provides a full interactive terminal interface:
Keyboard Shortcuts
| Key | Action |
|---|---|
Ctrl+D |
Send input |
Ctrl+L |
Clear input |
Ctrl+E |
Toggle history panel |
Ctrl+T |
New session |
Ctrl+B |
Toggle markdown/raw rendering |
Ctrl+G |
Edit config |
Ctrl+C |
Stop streaming (double-press to exit) |
Delete |
Delete selected history/session |
ESC |
Close modal dialogs |
Features
- Session management with automatic title generation
- History browsing and search
- Config editing modal
- Persistent chat history stored in
~/.config/agent-cli-tool/history/
Development
Project Structure
src/agent_cli_tool/
├── __init__.py # Entry point
├── agents/
│ ├── agent.py # Central orchestration
│ └── ai.py # OpenAI client wrapper
├── cli/
│ └── cli.py # Argument parser
├── config/
│ └── config.py # Configuration management
├── plugins/
│ ├── __init__.py # Plugin loader
│ ├── fetch.py # Web content fetcher
│ ├── file.py # File content injector
│ └── shell.py # Shell confirmation plugin
└── ui/
├── base.py # Base renderer
├── stdout.py # Plain text renderer
├── rich.py # Markdown renderer
└── tui.py # Interactive TUI renderer
Architecture
main() → Agent → Renderer (stdout/rich/tui) → Output
↓
CLI Args & Config
↓
Plugin System (before/after hooks)
↓
BaseAI → OpenAI API
Creating Plugins
Create a Python file in src/agent_cli_tool/plugins/:
# my_plugin.py
def before_ai_ask_hook(user_input: str, mode: str) -> str:
"""Process user input before sending to AI"""
# Modify user_input as needed
return user_input
def after_ai_ask_hook(ai_reply: str, mode: str) -> str:
"""Process AI response after receiving"""
# Modify ai_reply as needed
return ai_reply
Plugins are auto-discovered and loaded at runtime.
Dependencies
openai>=1.75.0- OpenAI API clientpython-dotenv>=1.1.0- Configuration managementrequests>=2.32.3- HTTP requestsrich>=14.0.0- Terminal renderingtextual>=6.11.0- TUI frameworkwcwidth>=0.2.14- Unicode width handling
License
MIT
Metadata
Release files for agent-cli-tool 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_cli_tool-0.2.2.tar.gz | 25.4 kB | Without provenance | Details for agent_cli_tool-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_cli_tool-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for agent_cli_tool-0.2.2-py3-none-any.whl |
Total release size: 54.9 kB
Release files / agent_cli_tool-0.2.2.tar.gz
| Download URL | agent_cli_tool-0.2.2.tar.gz |
|---|---|
| Size | 25.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1804383933f68f163079c715a674449aa8e3582311d3010bf2baa7f81750208b
|
|
BLAKE2b-256 checksum How to use checksums |
c106c9bfe7e8493f1021819e66ebe0b929b070657aa72f6ba45764b0fdb205b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / agent_cli_tool-0.2.2-py3-none-any.whl
| Download URL | agent_cli_tool-0.2.2-py3-none-any.whl |
|---|---|
| Size | 29.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ec256249f52af83ffc9cce660d109cce953a0e25a96d27857d54c6b20c880852
|
|
BLAKE2b-256 checksum How to use checksums |
495dcdf398cdced47c032f332e23bf871339b3c8782e73d65d2bb3d003c67f36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for agent-cli-tool 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.