{"_id":"@0xprathamesh/why-cli","name":"@0xprathamesh/why-cli","dist-tags":{"latest":"1.1.1"},"versions":{"1.1.1":{"name":"@0xprathamesh/why-cli","version":"1.1.1","description":"AI-first CLI debugger with safe simulation, code-aware fixes, and LangChain support for OpenAI and Ollama.","main":"dist/cli/index.js","bin":{"why":"dist/cli/index.js"},"preferGlobal":true,"scripts":{"build":"tsc","dev":"node dist/cli/index.js","check":"npm run build && npm pack --dry-run --cache ./.npm-pack-cache","prepublishOnly":"npm run build"},"keywords":["cli","debugging","developer-tools","openai","ollama","typescript","langchain"],"author":{"name":"why-cli contributors"},"license":"ISC","type":"commonjs","engines":{"node":">=18"},"dependencies":{"@langchain/core":"^0.3.58","@langchain/ollama":"^0.2.0","@langchain/openai":"^0.6.16"},"devDependencies":{"@types/node":"^25.5.2","typescript":"^6.0.2"},"_id":"@0xprathamesh/why-cli@1.1.1","gitHead":"0ae2bc6dc456903c435faaf02de959772bb81f93","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-tYg1K/ExU8xBQX5xe8lCKtReqva+n/gNR/IG5V8uFl79LdI3hpkwtQbp3LeF7rB7GlWMtfTD2UacIG+c3d6JiA==","shasum":"3d7932cb1b577c6615c34288afd8f035d1298b78","tarball":"https://registry.npmjs.org/@0xprathamesh/why-cli/-/why-cli-1.1.1.tgz","fileCount":32,"unpackedSize":169696,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDSANhyFvHsqQtdOKZEKHAoC4zpT3No1i55z3mr6K2KLAiAhodB9bvdp6BkuQeYuOV95W+KXOrbSv6Bcv74pSydHtQ=="}]},"_npmUser":{"name":"0xprathamesh","email":"prathameshpatil6499@gmail.com"},"directories":{},"maintainers":[{"name":"0xprathamesh","email":"prathameshpatil6499@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/why-cli_1.1.1_1775327529927_0.7460107054071414"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-04T18:32:09.821Z","1.1.1":"2026-04-04T18:32:10.082Z","modified":"2026-04-04T18:32:10.301Z"},"maintainers":[{"name":"0xprathamesh","email":"prathameshpatil6499@gmail.com"}],"description":"AI-first CLI debugger with safe simulation, code-aware fixes, and LangChain support for OpenAI and Ollama.","keywords":["cli","debugging","developer-tools","openai","ollama","typescript","langchain"],"author":{"name":"why-cli contributors"},"license":"ISC","readme":"# why\n\n`why` helps you understand what a terminal command will do, what went wrong, and what to try next.\n\nIt can:\n\n- run a command and explain failures\n- simulate risky commands before they change anything\n- stream live logs for long-running commands\n- use OpenAI or Ollama for AI explanations\n- read local code context when an error points into your project\n\n## Install\n\nGlobal install:\n\n```bash\nnpm install -g @0xprathamesh/why-cli\n```\n\nLocal development:\n\n```bash\nnpm install\nnpm run build\nnpm link\n```\n\nAfter that, the `why` command is available from any folder.\n\nPackage name on npm:\n\n```text\n@0xprathamesh/why-cli\n```\n\nRepository name on GitHub:\n\n```text\nwhy\n```\n\nThe install package is scoped, but the CLI command is still just:\n\n```bash\nwhy\n```\n\n## Docker\n\nBuild the image:\n\n```bash\ndocker build -t why-cli .\n```\n\nShow help from the container:\n\n```bash\ndocker run --rm why-cli --help\n```\n\nRun a command through `why` inside the container:\n\n```bash\ndocker run --rm why-cli --simulate -- git push origin main\n```\n\nIf you want to use your current project inside the container:\n\n```bash\ndocker run --rm -it -v \"$PWD:/workspace\" -w /workspace why-cli -- npm run build\n```\n\nIf you want AI config inside Docker, pass env values or an env file:\n\n```bash\ndocker run --rm --env-file .env why-cli --doctor\n```\n\n## Quick Start\n\nRun a normal command:\n\n```bash\nwhy -- npm run build\n```\n\nSimulate a risky command:\n\n```bash\nwhy --simulate -- git push origin main\n```\n\nRun a command for real even if `auto` mode would simulate it:\n\n```bash\nwhy --run -- git init\n```\n\nCheck AI setup:\n\n```bash\nwhy --doctor\n```\n\nInteractive setup:\n\n```bash\nwhy --setup\n```\n\n## How It Works\n\nFor every command, `why-cli` goes through this pipeline:\n\n`command -> classify -> risk -> simulate/run -> analyze -> explain`\n\nThat means:\n\n- safe read-only commands usually run in `auto` mode\n- risky state-changing commands are usually simulated in `auto` mode\n- failures are summarized in plain language\n- if AI is configured, `why-cli` adds an AI explanation on top\n\n## Modes\n\n`why-cli` has 3 execution modes.\n\n### `auto`\n\nDefault mode.\n\n- runs read-only commands\n- simulates risky commands\n\nExample:\n\n```bash\nwhy npm run build\nwhy git init\nwhy rm test.txt\n```\n\n### `run`\n\nRuns the command for real.\n\n```bash\nwhy --run -- git init\nwhy --run -- rm test.txt\n```\n\n### `simulate`\n\nNever runs the real command. It only does a safe preview when supported.\n\n```bash\nwhy --simulate -- git add .\nwhy --simulate -- npm install express\nwhy --simulate -- mkdir demo-folder\n```\n\n## Important Behavior\n\nIf you run:\n\n```bash\nwhy git init\n```\n\nyou may see simulation output instead of actual execution. That is expected in `auto` mode.\n\nIf you want the real command to run, use:\n\n```bash\nwhy --run -- git init\n```\n\n## AI Setup\n\nYou can configure AI once and stop passing keys or model flags every time.\n\nRecommended:\n\n```bash\nwhy --setup\n```\n\nThis writes config to:\n\n```bash\n~/.config/why-cli/.env\n```\n\nYou can also create that file manually.\n\nExample:\n\n```env\nWHY_PROVIDER=ollama\n\nOPENAI_API_KEY=\nOPENAI_MODEL=gpt-4.1\nOPENAI_BASE_URL=https://api.openai.com/v1\n\nOLLAMA_HOST=http://127.0.0.1:11434\nOLLAMA_MODEL=gemma3:4b\n\nWHY_SKILL=debug,fix\n```\n\nSupported config locations:\n\n- `.env.local` in the current folder\n- `.env` in the current folder\n- `.env.local` in parent folders\n- `.env` in parent folders\n- `~/.config/why-cli/.env`\n- `~/.env`\n\nCheck provider health:\n\n```bash\nwhy --doctor\n```\n\n## Providers\n\nSupported providers:\n\n- `auto`\n- `openai`\n- `ollama`\n- `none`\n\nExamples:\n\n```bash\nwhy --provider openai --explain -- npm test\nwhy --provider ollama --model gemma3:4b -- npm run build\nwhy --provider none -- npm start\n```\n\n## Common Commands\n\nRun commands:\n\n```bash\nwhy -- npm run build\nwhy -- npm start\nwhy -- python3 script.py\nwhy node -v\nwhy npm -v\nwhy cat README.md\n```\n\nSimulate commands:\n\n```bash\nwhy --simulate -- git add .\nwhy --simulate -- git commit -m \"test\"\nwhy --simulate -- git push\nwhy --simulate -- npm install\nwhy --simulate -- npm install express\nwhy --simulate -- npm publish\nwhy --simulate -- rm test.txt\nwhy --simulate -- mkdir test-folder\nwhy --simulate -- touch demo.txt\n```\n\nRun risky commands for real:\n\n```bash\nwhy --run -- git init\nwhy --run -- git commit -m \"ship\"\nwhy --run -- npm publish\n```\n\n## Failure Examples\n\nMissing package:\n\n```bash\nwhy --simulate -- npm install some-invalid-package-xyz\n```\n\nMissing file:\n\n```bash\nwhy --simulate -- rm non-existing-file\nwhy --simulate -- git add non-existing-file\n```\n\nExisting directory:\n\n```bash\nmkdir existing-folder\nwhy --simulate -- mkdir existing-folder\n```\n\nWrong Git push target:\n\n```bash\nwhy --simulate -- git push origin wrong-branch\n```\n\nBad build:\n\n```bash\nwhy --explain -- npm run build\n```\n\n## Long-Running Commands\n\n`why-cli` can stream logs for servers, watchers, and dev processes.\n\nExamples:\n\n```bash\nwhy -- npm start\nwhy --stream -- npm run dev\nwhy --no-stream -- npm run build\n```\n\nUse:\n\n- `--stream` to force live logs\n- `--no-stream` to wait until the command exits\n- `Ctrl+C` to stop the child process\n\n## Code-Aware Explanations\n\nWhen an error points to files in your project, `why-cli` can read local code context and include it in the explanation.\n\nThat helps with cases like:\n\n- TypeScript build errors\n- import or module resolution failures\n- stack traces with file paths\n- runtime failures pointing into your app code\n\nThis is most useful when you run `why` inside the project that failed.\n\n## Skills\n\nSkills shape how the AI explains the result.\n\nBuilt-in skills:\n\n- `debug`\n- `teach`\n- `fix`\n- `tests`\n- `security`\n- `perf`\n\nExamples:\n\n```bash\nwhy --skill debug --skill fix -- npm run build\nwhy --provider ollama --skill teach -- python3 script.py\nwhy --list-skills\n```\n\nYou can also set default skills in your config:\n\n```env\nWHY_SKILL=debug,fix\n```\n\n## Flags\n\n```text\n-h, --help\n-v, --version\n-s, --silent\n--json\n--no-color\n-r, --raw\n-e, --explain\n--mode <auto|run|simulate>\n--simulate\n--run\n--execute\n--provider <auto|none|openai|ollama>\n--model <name>\n--cwd <path>\n--timeout <ms>\n--skill <name>\n--list-skills\n--doctor\n--setup\n--stream\n--no-stream\n--api-key <key>\n--api-key-env <name>\n--openai-base-url <url>\n--ollama-host <url>\n```\n\n## Notes\n\n- Shell builtins like `cd` cannot change your parent shell session through `why-cli`.\n- In `auto` mode, risky commands are often simulated instead of executed.\n- If a command starts with flags that confuse parsing, use `--` before the command.\n\nExample:\n\n```bash\nwhy -- node -v\nwhy --simulate -- git status\n```\n\n\n\n## CI/CD\n\nGitHub Actions is included.\n\nCI workflow:\n\n- file: `.github/workflows/ci.yml`\n- runs on pushes to `main` and on pull requests\n- tests Node.js `18` and `20`\n- runs `npm ci`\n- runs `npm run build`\n- runs `npm pack --dry-run`\n\nRelease workflow:\n\n- file: `.github/workflows/release.yml`\n- runs on tags like `v1.1.0`\n- builds the project\n- publishes to npm\n\n","readmeFilename":"README.md","_rev":"1-0aed8ea376c6a0fa583e9288e9f197e8"}