astexlabs-ask 0.1.1

Lookup CLI commands easily

Ask 🔍

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

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:

git clone https://github.com/dtnewman/ask.git
cd ask

2. Install in editable mode:

macOS/Linux:

pip install -e .
# Or if you have multiple Python versions:
python3 -m pip install -e .

Windows:

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

3. Verify installation:

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

• Note: This project runs on top of LLM APIs like OpenAI, Google's Gemini, or Ollama.

📦 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

ask

Option 2: Direct Query

ask '<what you want to do>'

📝 Examples

# 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.

⚙️ Settings

Supported LLM Providers:

• OpenAI
• Google Gemini
• Ollama
• Azure OpenAI

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

ask --setup

OpenAI

To use OpenAI, you need an OpenAI account and a subscription. You can create an API key on this page.

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.

🐪 Using with Ollama

You can use Ask with Ollama as an alternative to hosted providers, which lets you run all commands locally. To set this up:

1. Install and start Ollama with a model of your choice

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

? 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 resource in your Azure subscription.

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

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

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

   ? 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 for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.