Skip to main content

how-cli

An AI-based CLI assistant to help you with command line & shell.

License: MIT

Demo

https://github.com/user-attachments/assets/effefe1a-c0ed-4b60-838c-98f992f6c25f

Features

  • ⚡ Deferred & Lazy LLM Initialization: Zero heavy imports during --help or startup, preventing startup crashes.
  • 🦙 Local LLM Support (Ollama): Run 100% offline with Ollama models (qwen2.5-coder, llama3.2, etc.) with no API keys required.
  • 🎯 Intelligent Environment & Project Context: Automatically detects your active shell, available package managers (apt, brew, dnf, pacman, etc.), and project root markers (package.json, Cargo.toml, pyproject.toml, go.mod, Dockerfile).
  • 🛡️ Safety Guardrails: Heuristic pattern detection warns against destructive commands (rm -rf, dd if=, mkfs, > /dev/sd, chmod -R 777, git reset --hard, git push --force, fork bombs, curl-pipe-to-shell) and gates execution with an explicit confirmation phrase.
  • 📋 Interactive Action Menu & Clipboard:
    • [E]xecute: Safely runs generated commands step-by-step, halting on non-zero exits.
    • [C]opy: Copies commands directly to your system clipboard via pyperclip.
    • [M]odify: Lets you edit commands inline before executing.
    • [A]bort: Cleanly exits with status 0.
  • 🔧 how fix Diagnostic Command: Inspects the last failed shell command from history or stderr and diagnoses fixes.

Installation

1. Using pip

pip install -U how-cli

2. Manual Installation

git clone https://github.com/FireHead90544/how-cli.git && cd how-cli
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Usage

$ how [OPTIONS] COMMAND [ARGS]...

Options:

  • -v, --version: Shows the version of the application.
  • --help: Show help message and exit.

Commands:

  • setup: Sets up the LLM provider, API key, custom model, or local endpoint.
  • to: Sends a task description to the LLM and returns the commands.
  • fix: Diagnoses the last failed command from shell history or stderr.

how setup

Configure your preferred LLM provider. Supports both cloud providers (OpenAI, Anthropic, Google, Groq) and local models via Ollama.

Interactive Mode:

how setup

Non-Interactive Mode:

# Using local Ollama (no API key needed!)
how setup --no-interactive --provider Ollama --model qwen2.5-coder:latest --endpoint http://localhost:11434

# Using OpenAI
how setup --no-interactive --provider OpenAI --api-key "sk-..." --model gpt-4o

# Using Groq
how setup --no-interactive --provider GroqLLaMa --api-key "gsk_..."

how to

Translates a natural language query into concrete shell commands tailored to your system and project.

how to "find all files larger than 100MB"
how to "install dependencies"

After commands are generated, the interactive action menu appears:

Options: [E]xecute | [C]opy | [M]odify | [A]bort
Select an action [e/c/m/a/E/C/M/A] (a):

Safety Guardrails

When a destructive command is detected (e.g. rm -rf, git push --force), how warns you with a prominent alert panel:

╭─────────────────────────── SAFETY GUARDRAIL ALERT ───────────────────────────╮
│ WARNING: Destructive or High-Risk Command(s) Detected!                       │
│ • Recursive Force Delete: rm -rf node_modules                                │
│   Permanently deletes files and directories recursively without              │
│ confirmation.                                                                │
│                                                                              │
│ To prevent accidental damage, type the exact confirmation phrase:            │
│ I UNDERSTAND THE RISKS                                                       │
╰──────────────────────────────────────────────────────────────────────────────╯

Typing y is rejected; you must explicitly enter I UNDERSTAND THE RISKS before execution is permitted.


how fix

Diagnoses why your last command failed and suggests the fix.

# Automatically read the last failed command from ~/.bash_history or ~/.zsh_history:
how fix

# Provide the command and stderr explicitly:
how fix -c "git push origin main" -e "error: failed to push some refs" -x 1

Providers

Provider Default Model Package Requires Key Tested
Ollama (Local) qwen2.5-coder:latest langchain-ollama ❌ No ✅
GoogleGenAI gemma-4-31b-it langchain-google-genai ✅ Yes ✅
GoogleVertexAI gemma-4-31b-it langchain-google-vertexai ✅ Yes ❌
GroqMistralAI mixtral-8x7b-32768 langchain-groq ✅ Yes ✅
GroqLLaMa qwen/qwen3.8-27b langchain-groq ✅ Yes ✅
OpenAI gpt-4o langchain-openai ✅ Yes ✅
Anthropic claude-3-5-sonnet-20240620 langchain-anthropic ✅ Yes ✅

Shell Integration

You can bind how to directly to a keyboard shortcut (e.g. Ctrl+G) in your shell to immediately convert your typed command buffer into an AI prompt:

Zsh (~/.zshrc)

how-widget() {
  BUFFER="how to \"$BUFFER\""
  zle accept-line
}
zle -N how-widget
bindkey '^G' how-widget

Bash (~/.bashrc)

how-widget() {
  local cmd="how to \"$READLINE_LINE\""
  READLINE_LINE=""
  eval "$cmd"
}
bind -x '"\C-g": how-widget'

License

how-cli is licensed under the MIT License. See LICENSE for details.

Honourable Mentions

This project is inspired by kynnyhsap's how.

Maintainers

Metadata

Release files for how-cli 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for how-cli 0.3.0
File Size Uploaded Provenance Actions
how_cli-0.3.0.tar.gz 23.1 kB Without provenance Details for how_cli-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for how-cli 0.3.0
File Interpreter ABI Platform Actions
how_cli-0.3.0-py3-none-any.whl Python 3 none any Details for how_cli-0.3.0-py3-none-any.whl

Total release size: 44.5 kB

Release files / how_cli-0.3.0.tar.gz

Download URL how_cli-0.3.0.tar.gz
Size 23.1 kB
Tags Source
SHA-256 checksum
How to use checksums
627369dd929e49c7248ed703075811bcbe709f2f43462bfab10d2fcbf3d7a386
BLAKE2b-256 checksum
How to use checksums
fe963acfa78c05a72712629d014ffe807084cc8e5fe3dc0f03489657ea41a49a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.15

Release files / how_cli-0.3.0-py3-none-any.whl

Download URL how_cli-0.3.0-py3-none-any.whl
Size 21.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ea8a2871a469ca745b58cb64ba3b30838667d98de2d4a109f285f4dc7671312c
BLAKE2b-256 checksum
How to use checksums
f9fbe1dff7e315408f6c425e1e5836952e5a084b30633b1198fca29013c34858
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.15

Security for how-cli 0.3.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page