Terminal-Pilot 0.1.6

A minimalist CLI tool to connect to OpenRouter and chat with free AI models directly from your terminal.

Terminal Pilot

A minimalist, interactive CLI tool to connect to OpenRouter and chat with free AI models directly from your terminal.

Installation

You can install Terminal Pilot globally directly from PyPI:

pip install Terminal-Pilot

Configuration

Zero configuration required!

Just run tp start. If you don't have an OpenRouter API key set up, the CLI will interactively ask you for it and securely save it for future sessions.

If you ever need to update or change your OpenRouter API key, just run:

tp auth

Usage

Start the interactive assistant from anywhere in your terminal:

tp start

Inside the interactive chat, you can instantly load files into the AI's memory by using the /read command. You can read files in your current folder, or provide paths to files in other folders:

? You: /read requirements.md
✓ Reading requirements.md...
? You: /read src/components/App.jsx
✓ Reading src/components/App.jsx...
? You: /read C:\Users\azhar\Desktop\error.log
✓ Reading C:\Users\azhar\Desktop\error.log...
? You: Give me a summary of these files.

Changing Models Mid-Chat

If a model hits a rate limit or you want to switch to a different one, you don't need to exit. Just type /model to hot-swap:

? You: /model
✓ Switched model to: google/gemma-3

Pipe Support (stdin)

You can pipe data directly into the AI to analyze logs, code, or command outputs instantly without opening an interactive chat:

cat error.log | tp ask "Why is this crashing?"
git diff | tp ask "Write a commit message for these changes"
tp ask "What is the command to undo a git commit?"

Personas & Rules

Terminal Pilot ships with a default persona out of the box (a lazy senior developer focused on YAGNI). To disable or modify the default persona, simply edit or clear the ~/.terminal_pilot_default.md file that gets automatically generated in your home directory.

You can hot-swap the AI's personality or rules at any point—even mid-chat—using the /rule command:

? You: /rule concise
✓ Rule loaded mid-chat: concise

Terminal Pilot supports several ways to load rules:

1. Built-in Personas: Use our pre-configured shortcuts (e.g., ponytail, pirate, concise).
2. Local Files & Remote URLs: Pass any .md file or raw URL (/rule https://raw.github.../prompt.md).
3. Your Custom Aliases: Create a ~/.terminal_pilot_rules.json file in your home directory with your own shortcuts:

   {
     "hacker": "You are a 90s movie hacker...",
     "expert": "You are a senior python developer..."
   }
   

   Then simply type /rule hacker anywhere!

You can also start the CLI with specific rules instantly (and chain them):

tp start --rule pirate
tp start --rule https://example.com/rule.md --rule concise