howto

A privacy-first terminal assistant that respects your data.

howto is a lightweight CLI tool designed to generate terminal commands using your preferred LLM. Unlike other tools that may send your entire shell context to cloud servers, howto is designed to be minimal and private, sending only what you explicitly ask for.

---

Features

• Privacy-Centric › Your terminal environment stays local. Only your specific queries are sent to the LLM.
• Backend Agnostic › Works with Google's Gemini CLI, OpenAI-compatible APIs, or local models via LM Studio/Ollama.
• Interactive Editing › Refine generated commands with a feedback loop before execution.
• Safe Execution › Inspect privacy details and generated commands before running them.

---

Installation

To get started, clone the repository and install using pipx for an isolated environment.

1. Clone the repository

   git clone https://github.com/M7Saad/howto
   cd howto

Note: pipx is recommended for CLI tools because it installs them in an isolated environment, preventing dependency conflicts with your system Python while keeping the command globally accessible.

2. Install with pipx

   pipx install .

---

Configuration

howto supports multiple backends. Choose the one that fits your needs.

Option 1: Gemini CLI (Free & Generous)

Leverage Google's Gemini models via their CLI tool. This is a great option for free, high-quality generation.

1. Ensure you have the gemini CLI installed and authenticated.
2. Run configuration:

   howto --configure

3. Select Gemini CLI.

Option 2: Custom API (OpenAI / Local LLMs)

Connect to any OpenAI-compatible endpoint. This is perfect for using local models with LM Studio, Ollama, or connecting to OpenAI.

1. Run configuration:

   howto --configure

2. Select Custom.
3. Enter your Base URL and API Key:
   • OpenAI: https://api.openai.com/v1 (requires key)
   • LM Studio: http://localhost:1234/v1 (key usually ignored)

---

Usage

Simply type howto followed by your request.

howto list all docker containers

Interactive Edit Flow

If the generated command isn't quite right, you can choose to Edit it directly in the tool.

1. The tool presents a command.
2. Select Edit.
3. Provide feedback (e.g., "show hidden files too").
4. The tool regenerates the command based on your valid feedback.

[ Note ]
You may need sudo privileges for this command.

$ sudo ls -la

[ Execute ]  [ Edit ]  [ Cancel ]

Keyboard Shortcuts

Quickly navigate the interactive menu using these keys:

• Navigation: Left / Right arrows
• Select: Enter
• Shortcuts:
  • y › Execute
  • e › Edit
  • n / c › Cancel