how - Lightweight AI assistant for your CLI

Enter how – the slick, AI-powered sidekick that turns your "WTF do I type?" moments into commands. Built in Go for speed, this cross-platform tool taps into AI to generate commands via top LLMs.

Features

• Fast and dependency-free.
• Runs on Linux, macOS, Windows.
• Support for OpenRouter (default) and OpenAI.
• Configurable models and providers.
• Optional command execution with confirmation.
• Saves a local history of generated commands.

Usage

Generate a command

Ask away:

$ how find all files named docker-compose.yml
find . -type f -name "docker-compose.yml"

$ how check memory usage in a human readable format
free -h

$ how kill process on port 8080
lsof -ti:8080 | xargs kill -9

Pro Tip: Override the model with --model "google/gemini-2.5-flash" or set a default via how set-model. Defaults to anthropic/claude-haiku-4.5.

Run the generated command (optional)

If you want how to execute what it generates:

$ how --run find all files named docker-compose.yml
find . -type f -name "docker-compose.yml"
# Prompts: Run this command? [y/N]

Skip confirmation (use carefully):

$ how --run --yes kill process on port 8080
lsof -ti:8080 | xargs kill -9

Reuse the last generated command

Print the last generated command:

$ how last
echo hi

Run the last generated command (with confirmation unless --yes):

$ how last --run
$ how last --run --yes

Install

Download Pre-built Binary (Recommended)

Download the latest release for your platform from GitHub Releases:

1. Download the archive for your OS/architecture
2. Extract the binary:

   # Linux/macOS
   tar -xzf how-v*.tar.gz
   
   # Windows
   # Extract the .zip file

3. Move to your PATH:

   # Linux/macOS
   sudo mv how /usr/local/bin/
   
   # Windows
   # Move how.exe to a directory in your PATH

Arch Linux (AUR)

For Arch Linux users, install via AUR:

yay -S how-cli

Build from Source

1. Clone the repo:

   git clone https://github.com/patrykgruszka/how-cli.git
   cd how-cli

2. Run the installer (handles build and PATH):

   chmod +x install.sh
   ./install.sh

Alternatives: Build manually with go build or use make install. For cross-platform binaries, run make cross (outputs to dist/).

Setup

You need an API key.

1. OpenRouter (Default): Get a key from openrouter.ai/keys.
2. OpenAI: Get a key from platform.openai.com.

Run setup to select your provider and save your key:

how setup

Paste your key—it's stored in ~/.config/how/config.yaml (or equivalent on Windows).

Config & History

Config

Variables are stored in ~/.config/how/config.yaml.

• provider: openrouter (default) or openai
• api_key: your API key
• model: default model ID

History

Generated commands are saved locally to:

• ~/.config/how/history.jsonl (or equivalent on Windows)

This is used by how last.

Flags

• --model: override the configured/default model for a single invocation
• --run: execute the generated command (prompts for confirmation)
• --yes: skip confirmation when used with --run
• --debug: print debug information (provider, endpoint, model, prompt)