Metadata-Version: 2.4
Name: astexlabs-ask
Version: 0.1.1
Summary: Lookup CLI commands easily
Project-URL: Repository, https://github.com/astexlabs/ask
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.72.0
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pyperclip>=1.9.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: questionary>=2.1.0
Requires-Dist: rich>=13.9.4
Provides-Extra: dev
Requires-Dist: ruff>=0.11.2; extra == "dev"
Requires-Dist: isort>=5.13.2; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Provides-Extra: azure
Requires-Dist: azure-identity>=1.20.0; extra == "azure"
Dynamic: license-file

# Ask 🔍

[![PyPI version](https://badge.fury.io/py/ask.svg)](https://badge.fury.io/py/ask)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Ask helps you remember (or discover) terminal commands using natural language.

![Description](./.github/demo.gif)


### For Local Development

To install ask locally for development where you can make changes to the code:

#### Prerequisites
- Python 3.10 or higher
- Git

#### Installation Steps

1. **Clone the repository**:
```bash
git clone https://github.com/dtnewman/ask.git
cd ask
```

2. **Install in editable mode**:

**macOS/Linux:**
```bash
pip install -e .
# Or if you have multiple Python versions:
python3 -m pip install -e .
```

**Windows:**
```cmd
pip install -e .
# Or if you have multiple Python versions:
python -m pip install -e .
```

3. **Verify installation**:
```bash
ask --help
```

#### How Editable Installation Works
- Creates a link to your local repository instead of copying files
- Any changes you make to files in `src/ask/` are immediately reflected when you run `ask`
- No need to reinstall after making changes

#### Python Version Notes
- **macOS**: If you get a "command not found" error, you may need Python 3.10+. Install via Homebrew: `brew install python@3.11`
- **Linux**: Use your package manager to install Python 3.10+ (e.g., `apt install python3.11` on Ubuntu)
- **Windows**: Download Python 3.10+ from [python.org](https://python.org)

- **Note:** This project runs on top of LLM APIs like OpenAI, Google's Gemini, or [Ollama](https://ollama.com/).

## 📦 Dependencies

For clipboard functionality (copying and pasting) to work properly, you may need to install:

- On Linux: `xclip` or `xsel` (for X11) or `wl-clipboard` (for Wayland)
- On macOS: No additional dependencies needed
- On Windows: No additional dependencies needed

## 🎮 Usage

### Option 1: Interactive Mode

```bash
ask
```

### Option 2: Direct Query

```bash
ask '<what you want to do>'
```

## 📝 Examples

```bash
# Find running processes
ask 'show all running python processes'

# File operations
ask 'find all .py files modified in the last 24 hours'

# System information
ask 'show disk usage for current directory'

# Network commands
ask 'check if google.com is reachable'

# Git operations
ask 'show uncommitted changes in git'
```

## 🛡️ Safety Considerations

⚠️ Commands are generated by LLMs. While the tool attempts to flag dangerous commands, it may not always do so. Use caution.

![Example of dangerous command warning](./.github/dangerous_example.png)

## ⚙️ Settings

### **Supported LLM Providers:**

- OpenAI
- Google Gemini
- Ollama
- Azure OpenAI

You can update your API keys and provider settings by running:

```bash
ask --setup
```

### OpenAI

To use OpenAI, you need an OpenAI account and a subscription. You can create an API key on [this page](https://platform.openai.com/settings/organization/api-keys).

### Google Gemini (Free)

To use Google's Gemini models, you need a Google AI Studio account. You can create a Gemini API key in [Google AI Studio](https://aistudio.google.com/).

## 🐪 Using with Ollama

You can use Ask with [Ollama](https://ollama.ai/) as an alternative to hosted providers, which lets you run all commands locally. To set this up:

1. Install and start [Ollama](https://ollama.com/) with a model of your choice

2. Run `ask --setup` and put in the proper settings. For example:

``` bash
? Pick your LLM provider: Ollama
? Enter the Ollama URL: http://localhost:11434/v1
? Enter the model to use (e.g. llama3.2): llama3.2
```

### Azure OpenAI

To use Azure OpenAI, you’ll need access to an [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-services/openai-service) resource in your Azure subscription.

1. Create a deployment of the model you want to use (e.g., `gpt-4o`, `gpt-4o-mini` etc.).

1. Install required Azure depedencies with `pip install ask[azure]`.

1. Run `ask --setup` and put in the proper settings. For example:

    ``` bash
    ? Pick your LLM provider: Azure OpenAI
    ? Azure OpenAI account name (e.g. my-openai-resource): my-openai-resource
    ? Azure OpenAI API key (leave blank to use Entra ID / keyless auth):
    ? Azure OpenAI deployment name (e.g. gpt-4, gpt-4o, etc): gpt-4o
    ? Azure OpenAI API version: 2025-03-01-preview
    ```

    > **Note:** Model version must be 2024-08-06 or newer.  
    > API version must be 2024-08-01-preview or newer.

Note that to switch backends, you can re-run `ask --setup` again at any time.

## 🤝 Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
