why

why helps you understand what a terminal command will do, what went wrong, and what to try next.

It can:

• run a command and explain failures
• simulate risky commands before they change anything
• stream live logs for long-running commands
• use OpenAI or Ollama for AI explanations
• read local code context when an error points into your project

Install

Global install:

npm install -g @0xprathamesh/why-cli

Local development:

npm install
npm run build
npm link

After that, the why command is available from any folder.

Package name on npm:

@0xprathamesh/why-cli

Repository name on GitHub:

why

The install package is scoped, but the CLI command is still just:

why

Docker

Build the image:

docker build -t why-cli .

Show help from the container:

docker run --rm why-cli --help

Run a command through why inside the container:

docker run --rm why-cli --simulate -- git push origin main

If you want to use your current project inside the container:

docker run --rm -it -v "$PWD:/workspace" -w /workspace why-cli -- npm run build

If you want AI config inside Docker, pass env values or an env file:

docker run --rm --env-file .env why-cli --doctor

Quick Start

Run a normal command:

why -- npm run build

Simulate a risky command:

why --simulate -- git push origin main

Run a command for real even if auto mode would simulate it:

why --run -- git init

Check AI setup:

why --doctor

Interactive setup:

why --setup

How It Works

For every command, why-cli goes through this pipeline:

command -> classify -> risk -> simulate/run -> analyze -> explain

That means:

• safe read-only commands usually run in auto mode
• risky state-changing commands are usually simulated in auto mode
• failures are summarized in plain language
• if AI is configured, why-cli adds an AI explanation on top

Modes

why-cli has 3 execution modes.

auto

Default mode.

• runs read-only commands
• simulates risky commands

Example:

why npm run build
why git init
why rm test.txt

run

Runs the command for real.

why --run -- git init
why --run -- rm test.txt

simulate

Never runs the real command. It only does a safe preview when supported.

why --simulate -- git add .
why --simulate -- npm install express
why --simulate -- mkdir demo-folder

Important Behavior

If you run:

why git init

you may see simulation output instead of actual execution. That is expected in auto mode.

If you want the real command to run, use:

why --run -- git init

AI Setup

You can configure AI once and stop passing keys or model flags every time.

Recommended:

why --setup

This writes config to:

~/.config/why-cli/.env

You can also create that file manually.

Example:

WHY_PROVIDER=ollama

OPENAI_API_KEY=
OPENAI_MODEL=gpt-4.1
OPENAI_BASE_URL=https://api.openai.com/v1

OLLAMA_HOST=http://127.0.0.1:11434
OLLAMA_MODEL=gemma3:4b

WHY_SKILL=debug,fix

Supported config locations:

• .env.local in the current folder
• .env in the current folder
• .env.local in parent folders
• .env in parent folders
• ~/.config/why-cli/.env
• ~/.env

Check provider health:

why --doctor

Providers

Supported providers:

• auto
• openai
• ollama
• none

Examples:

why --provider openai --explain -- npm test
why --provider ollama --model gemma3:4b -- npm run build
why --provider none -- npm start

Common Commands

Run commands:

why -- npm run build
why -- npm start
why -- python3 script.py
why node -v
why npm -v
why cat README.md

Simulate commands:

why --simulate -- git add .
why --simulate -- git commit -m "test"
why --simulate -- git push
why --simulate -- npm install
why --simulate -- npm install express
why --simulate -- npm publish
why --simulate -- rm test.txt
why --simulate -- mkdir test-folder
why --simulate -- touch demo.txt

Run risky commands for real:

why --run -- git init
why --run -- git commit -m "ship"
why --run -- npm publish

Failure Examples

Missing package:

why --simulate -- npm install some-invalid-package-xyz

Missing file:

why --simulate -- rm non-existing-file
why --simulate -- git add non-existing-file

Existing directory:

mkdir existing-folder
why --simulate -- mkdir existing-folder

Wrong Git push target:

why --simulate -- git push origin wrong-branch

Bad build:

why --explain -- npm run build

Long-Running Commands

why-cli can stream logs for servers, watchers, and dev processes.

Examples:

why -- npm start
why --stream -- npm run dev
why --no-stream -- npm run build

Use:

• --stream to force live logs
• --no-stream to wait until the command exits
• Ctrl+C to stop the child process

Code-Aware Explanations

When an error points to files in your project, why-cli can read local code context and include it in the explanation.

That helps with cases like:

• TypeScript build errors
• import or module resolution failures
• stack traces with file paths
• runtime failures pointing into your app code

This is most useful when you run why inside the project that failed.

Skills

Skills shape how the AI explains the result.

Built-in skills:

• debug
• teach
• fix
• tests
• security
• perf

Examples:

why --skill debug --skill fix -- npm run build
why --provider ollama --skill teach -- python3 script.py
why --list-skills

You can also set default skills in your config:

WHY_SKILL=debug,fix

Flags

-h, --help
-v, --version
-s, --silent
--json
--no-color
-r, --raw
-e, --explain
--mode <auto|run|simulate>
--simulate
--run
--execute
--provider <auto|none|openai|ollama>
--model <name>
--cwd <path>
--timeout <ms>
--skill <name>
--list-skills
--doctor
--setup
--stream
--no-stream
--api-key <key>
--api-key-env <name>
--openai-base-url <url>
--ollama-host <url>

Notes

• Shell builtins like cd cannot change your parent shell session through why-cli.
• In auto mode, risky commands are often simulated instead of executed.
• If a command starts with flags that confuse parsing, use -- before the command.

Example:

why -- node -v
why --simulate -- git status

CI/CD

GitHub Actions is included.

CI workflow:

• file: .github/workflows/ci.yml
• runs on pushes to main and on pull requests
• tests Node.js 18 and 20
• runs npm ci
• runs npm run build
• runs npm pack --dry-run

Release workflow:

• file: .github/workflows/release.yml
• runs on tags like v1.1.0
• builds the project
• publishes to npm