hashcli 0.5.1

Hash - Intelligent CLI system with dual-mode functionality (LLM chat and command proxy)

Hash CLI

Your AI Terminal Assistant That Actually Gets Things Done

Talk to your terminal in plain English. Get instant help with commands, debug errors, analyze code, and automate workflows—all without leaving your shell.

Quick Start • Features • Examples • Plugins • Docs

---

What is Hash CLI?

Hash CLI transforms your terminal into an intelligent workspace. Instead of memorizing commands, googling syntax, or switching between tabs, just ask your terminal what to do in natural language. Hash CLI understands your intent, executes commands safely, and learns your workflow.

Stop doing this:

# Opens browser, searches "how to find large files linux"
# Copies command, pastes back
# Gets error, searches again...

Start doing this:

# find all files larger than 100MB in my home directory

Hash CLI figures out the command, shows you what it will run, and executes it with your approval.

---

Why Choose Hash CLI?

Work Faster

No more context switching. Ask questions, debug errors, and execute commands without leaving your terminal. Hash CLI integrates seamlessly into your existing workflow with optional # prefix support.

Stay Safe

Built-in guardrails protect your system. Every destructive operation requires confirmation. Commands are checked against allow/deny lists. Dangerous patterns are blocked automatically.

Choose Your Brain

Use OpenAI, Anthropic (Claude), or Google (Gemini) models. Switch providers and models on the fly. Your choice, your control.

Extend Infinitely

The plugin system lets you add custom slash commands in minutes. Install community plugins or write your own. Make Hash CLI work exactly how you want.

Keep Context

Full conversation history is preserved. Reference past sessions, review what worked, and build on previous interactions.

---

Quick Start

Installation

Install Hash CLI with pipx (recommended) or uv:

# Using pipx (works across all virtual environments)
pipx install hashcli

# Or using uv
uv tool install hashcli

# Or using pip
pip install hashcli

Setup

Set up shell integration for the magical # prefix:

hashcli --setup

Configure your API key (choose one):

# Option 1: Set environment variable
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"
export GOOGLE_API_KEY="your-key-here"

# Option 2: Use interactive setup wizard
hashcli --config

Start Using

That's it! Now start asking:

# show disk usage in human readable format
# what git branches exist and which one am I on
# find all python files modified in the last week
# explain what this error means: "ModuleNotFoundError: No module named 'requests'"

---

Real-World Examples

Debugging & Troubleshooting

# my docker container keeps crashing, help me debug it
# why is port 8080 already in use and how do I fix it
# my git push was rejected, what should I do

Hash CLI analyzes the situation, checks logs, and suggests solutions.

Code Analysis & Understanding

# analyze the code quality of src/main.py
# what does this function do? <paste code>
# find all TODO comments in this project

Get instant insights with AST-based analysis for Python and metrics for JavaScript/Java.

System Administration

# show me which processes are using the most memory
# clean up docker images I'm not using
# backup my Documents folder to external drive

Perfect for sysadmins who want intelligent assistance without memorizing every flag.

Development Workflow

# show last 10 commits with author names
# find files that import pandas but don't use it
# what's the difference between staging and production config

Streamline your daily development tasks with natural language.

Learning & Discovery

# how do I use awk to extract the third column
# show me examples of python decorators
# what's the difference between RUN and CMD in Dockerfile

Your terminal becomes a patient teacher, explaining concepts and showing examples.

---

Features

Natural Language Interface

Ask questions, describe problems, and give instructions in plain English. Hash CLI translates your intent into precise commands and actions.

Multi-Provider AI Support

• OpenAI (GPT-4, GPT-3.5)
• Anthropic (Claude Opus, Sonnet, Haiku)
• Google (Gemini Pro, Gemini Flash)

Switch models and providers instantly with CLI flags or config files.

Intelligent Tool Calling

Hash CLI can:

• Execute shell commands with timeout protection and security checks
• Read and write files with safety confirmations
• Search the web via DuckDuckGo for up-to-date information
• Analyze code with AST parsing for Python and metrics for JS/Java
• Navigate directories and inspect file structures

Every tool action is transparent and requires your approval.

Extensible Plugin System

Create custom slash commands for your specific workflow:

# Install a plugin
hashcli --add-cmd plugins/model.py

# Use it
hashcli /model list
hashcli /model switch gpt-4

Build plugins in minutes. Check plugins/ directory for examples.

Smart Configuration

Hash CLI adapts to your environment:

1. CLI flags (highest priority)
2. Environment variables (HASHCLI_*)
3. User config (~/.hashcli/config.toml)
4. System config (/etc/hashcli/config.toml)
5. Sensible defaults

Override anything, anytime, from anywhere.

Conversation History

Every interaction is saved:

hashcli /history          # List all sessions
hashcli /history show 5   # View session details
hashcli /history clear    # Clean up old conversations

Within an interactive shell, hashcli and hcli now reuse one conversation per shell session. Use --new-session to start a fresh conversation for a single invocation. If HASHCLI_SESSION_ID is set, that value is used instead of auto shell-session scoping.

Review past solutions, replay successful commands, and learn from history.

---

Safety & Security

Hash CLI is designed with security as a first-class feature:

Confirmation Required

• Shell execution requires explicit approval
• File writes show exactly what will change
• Destructive operations are highlighted

Command Filtering

• Blocked commands list prevents dangerous operations
• Optional allowed commands whitelist for strict environments
• Shell operators (|, ;, &&) are restricted by default

Transparent Execution

• Every command is shown before execution
• Tool calls are logged and auditable
• No hidden actions or background processes

Configurable Paranoia

• Use --no-confirm only when you trust the workflow
• Customize allow/deny lists per environment
• Set timeouts to prevent runaway processes

---

Advanced Configuration

Provider & Model Selection

# Use specific model
hashcli --model gpt-4 "explain quantum computing"

# Switch provider
hashcli --provider anthropic "debug my code"

# Show current config
hashcli --show-config

Quiet & Streaming Modes

# Minimal output for scripting
hashcli --quiet "list all .py files"

# Stream responses as they generate
hashcli --stream "write a long explanation"

Environment Variables

# Set default provider
export HASHCLI_PROVIDER=anthropic
export HASHCLI_MODEL=claude-opus-4

# Configure behavior
export HASHCLI_NO_CONFIRM=true
export HASHCLI_DEBUG=true

Configuration File

Create ~/.hashcli/config.toml:

[default]
provider = "anthropic"
model = "claude-sonnet-4"
stream = true
require_confirmation = true

[providers.anthropic]
api_key = "your-key-here"

[security]
blocked_commands = ["rm -rf /", "dd if=", "mkfs"]
allowed_commands = []  # empty = allow all (except blocked)

---

Plugin Development

Create Your Own Plugin

# my_plugin.py
from typing import List
from hashcli.command_proxy import Command
from hashcli.config import HashConfig

class MyPluginCommand(Command):
    """Custom functionality for my workflow"""

    def execute(self, args: List[str], config: HashConfig) -> str:
        # Your plugin logic here
        return f"Plugin executed with args: {args}"

    def get_help(self) -> str:
        return "Usage: /my-plugin [args]\nDoes something useful."

    def validate_args(self, args: List[str]) -> tuple[bool, str]:
        return True, ""

Install & Use

# Install your plugin
hashcli --add-cmd my_plugin.py

# Use it immediately
hashcli /my-plugin arg1 arg2

Plugins are stored in ~/.hashcli/plugins/ and loaded automatically on startup.

---

CLI Reference

# Interactive mode
hashcli "your question here"

# Configuration
hashcli --config          # Guided setup wizard
hashcli --setup           # Install shell integration
hashcli --show-config     # Display current settings

# Plugin management
hashcli --add-cmd <file>  # Install plugin

# Built-in commands
hashcli /help             # Show available commands
hashcli /history          # Manage conversation history
hashcli /model list       # List available models (with plugin)

# Flags
--model MODEL             # Override model
--provider PROVIDER       # Override provider (openai/anthropic/google)
--no-confirm, -y          # Skip confirmations (use with caution)
--new-session             # Start a fresh conversation for this run
--debug, -d               # Enable debug output
--quiet, -q               # Minimal output
--stream                  # Stream responses

---

Contributing

Hash CLI is open source and welcomes contributions:

• Report bugs and request features via GitHub Issues
• Submit pull requests for bug fixes and enhancements
• Share your plugins with the community
• Improve documentation and examples

---

License

Hash CLI is released under the MIT License. See LICENSE file for details.

---

Support

• Documentation: Check this README and CLAUDE.md for development details
• Issues: GitHub Issues
• Questions: Open a GitHub Discussion or Issue

---

Stop memorizing commands. Start talking to your terminal.

Install Now • Read the Docs • Write a Plugin