Metadata-Version: 2.4
Name: terminal-ask
Version: 0.1.0
Summary: Your terminal oracle — ask natural-language questions, get shell commands, powered by OpenRouter.
Author: Ramin Nikzad-Langerodi
License: MIT
Keywords: cli,shell,openrouter,llm,assistant
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

```
  ░█████╗░░██████╗██╗░░██╗
  ██╔══██╗██╔════╝██║░██╔╝
  ███████║╚█████╗░█████═╝░
  ██╔══██║░╚═══██╗██╔═██╗░
  ██║░░██║██████╔╝██║░╚██╗
  ╚═╝░░╚═╝╚═════╝╚═╝░░╚═╝
```
> *Your terminal command oracle. Powered by [OpenRouter](https://openrouter.ai).*

```
$ ask how do I find files larger than 100MB
find / -type f -size +100M
(copied to clipboard)
```

```
$ ask --verbose how do I find files larger than 100MB
find / -type f -size +100M

  find      — search for files in a directory hierarchy
  /         — start from the root (use . for current directory)
  -type f   — match files only, not directories
  -size +100M — only files larger than 100 megabytes
```

## Requirements

- Python 3.8+
- An [OpenRouter API key](https://openrouter.ai/keys)
- On Linux: `xclip` or `xsel` for clipboard support

## Installation

ask-cli is a standard installable Python package (`pyproject.toml`, console-script entry point).

### Recommended: pipx

```bash
pipx install .
```

### pip (editable, good for development)

```bash
pip install -e .
```

### Windows helper script

```powershell
.\install.ps1
```

This just runs `pip install --user -e .` for you. If the `ask` command isn't found afterward, make sure your Python user Scripts directory is on PATH, or use `pipx install .` instead.

After installing, restart your terminal, then:

```powershell
ask how do I list open ports
```

## First Run

On first use, the setup wizard will guide you through:

1. Pasting your OpenRouter API key
2. Choosing a default model

```
$ ask how do I create an SSH key
=== ask setup ===

Paste your OpenRouter API key (https://openrouter.ai/keys):
> sk-or-...
```

You can re-run setup at any time with `ask --setup`.

## Usage

```
ask [options] <question>
```

### Options

| Flag | Description |
|---|---|
| `--verbose` | Include an explanation alongside the command |
| `--copy`, `-c` | Copy the result to clipboard |
| `--model <id>` | Switch the default model (saved permanently) |
| `--setup` | Re-run the setup wizard (key + model selection) |
| `--reset-key` | Remove the saved API key |
| `--list-models` | List models currently available (live-checked against OpenRouter) |
| `--version` | Show the installed version |

### Examples

```bash
# Get a command (auto-copied if single line)
ask how do I list open ports

# Get a command with explanation
ask --verbose how do I recursively delete empty folders

# Switch model
ask --model openai/gpt-4o-mini

# Ask with the new model and copy result
ask -c how do I tar a directory excluding node_modules
```

## Models

The setup wizard offers a curated shortlist, checked against OpenRouter's live model catalog on each run (cached for 24h, with an offline fallback so the tool still works without network access):

| Model | Notes |
|---|---|
| `anthropic/claude-haiku-4.5` | Default — fast, great for shell/code tasks |
| `openai/gpt-5.6-luna` | Fast, cheap, good for shell tasks |
| `google/gemma-4-26b-a4b-it:free` | Free tier via OpenRouter |

Run `ask --list-models` to see the current, live-checked shortlist at any time.

You can also set any OpenRouter model directly:

```bash
ask --model anthropic/claude-sonnet-4.5
```

## Configuration

Config is stored at `~/.config/ask/config.json`:

```json
{
  "api_key": "sk-or-...",
  "model": "anthropic/claude-haiku-4.5"
}
```

## System Prompts

Prompts are bundled as Markdown files inside the package:

- `src/ask_cli/prompts/default.md` — used for standard (concise) responses
- `src/ask_cli/prompts/verbose.md` — used when `--verbose` is passed

Edit these files (and reinstall) to customize the assistant's behavior.

## Development

```bash
pip install -e ".[dev]"
pytest
```

CI runs the test suite on Windows and Linux via GitHub Actions (`.github/workflows/ci.yml`).

## Clipboard Behavior

- **Single command returned**: auto-copied to clipboard
- **Multiple commands returned**: only copied if `--copy` / `-c` is passed

## Author

Created and maintained by **Ramin Nikzad-Langerodi**

info@bottleneck-analytics.com

## License

MIT — see [LICENSE](LICENSE).
