tutr 0.1.4

AI-powered terminal assistant that generates shell commands from natural language.

tutr - Terminal Utility for Con(T)extual Responses

A stupid simple, AI-powered terminal assistant that generates commands from natural language.

What does it do?

Generates terminal commands from natural language queries.

> tutr git create and switch to a new branch called testing

  git checkout -b testing

> tutr go back to the previous directory

  cd -

Installation

Requires Python 3.10+.

pipx install tutr

Or run it without installing:

uvx tutr

For development from source:

git clone https://github.com/spi/tutr.git
cd tutr
uv sync

Setup

On first run, tutr launches an interactive setup to select your provider, model, and API key:

$ tutr git "show recent commits"

Welcome to tutr! Let's get you set up.

Select your LLM provider:
  1. Gemini
  2. Anthropic
  3. OpenAI
  4. Ollama (local, no API key needed)

  Enter choice (1-4): 1

Enter your Gemini API key:
  API key:

Select a model:
  1. Gemini 3 Flash (recommended)
  2. Gemini 2.0 Flash
  3. Gemini 2.5 Pro

  Enter choice (1-3): 1

Configuration saved to ~/.tutr/config.json

Setup is skipped if ~/.tutr/config.json already exists or provider API key environment variables are set.

Usage

tutr <command> <what you want to do>

Auto-start in Every Terminal

tutr is an interactive shell wrapper. To launch it automatically for every new interactive terminal, add this to your shell rc file.

Bash (~/.bashrc)

if [[ $- == *i* ]] && [[ -z "${TUTR_AUTOSTARTED:-}" ]] && [[ -z "${TUTR_SKIP_AUTOSTART:-}" ]]; then
  export TUTR_AUTOSTARTED=1
  exec tutr
fi

Zsh (~/.zshrc)

if [[ -o interactive ]] && [[ -z "${TUTR_AUTOSTARTED:-}" ]] && [[ -z "${TUTR_SKIP_AUTOSTART:-}" ]]; then
  export TUTR_AUTOSTARTED=1
  exec tutr
fi

Notes:

• TUTR_AUTOSTARTED prevents recursion when tutr sources your normal rc file.
• Set TUTR_SKIP_AUTOSTART=1 before opening a terminal to temporarily bypass autostart.
• Active wrapped shells show a prompt prefix (default [tutr]) and set TUTR_ACTIVE=1.
• Customize the prefix with TUTR_PROMPT_PREFIX (example: export TUTR_PROMPT_PREFIX="[ai]").
• Use tutr-cli ... if you want the original one-shot command generator behavior.

Examples

tutr git "create and switch to a new branch called testing"
tutr sed "replace all instances of 'foo' with 'bar' in myfile.txt"
tutr curl "http://example.com and display all request headers"

Arguments

Argument	Description
command	The terminal command to get help with (e.g., git, sed, curl)
query	What you want to do, in natural language

Options

Flag	Description
-h, --help	Show help message
-V, --version	Show version
-d, --debug	Enable debug logging
-e, --explain	Show LLM explanation and source for the generated command

Configuration

Config is stored in ~/.tutr/config.json. Environment variables override the config file.

Environment Variable	Description	Default
TUTR_MODEL	LLM model to use (litellm format)	gemini/gemini-3-flash-preview
GEMINI_API_KEY	Gemini API key	—
ANTHROPIC_API_KEY	Anthropic API key	—
OPENAI_API_KEY	OpenAI API key	—

You can also enable command explanations persistently in ~/.tutr/config.json:

{
  "show_explanation": true
}

To re-run setup, delete the config file:

rm ~/.tutr/config.json

Development

Run all quality checks:

uv run poe check

Run tests only:

uv run pytest

Lint and format:

uv run ruff check .
uv run ruff format .

Publishing to PyPI

Build and validate distribution artifacts:

uv sync
uv run poe dist

Upload to TestPyPI first:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=<testpypi-api-token>
uv run poe publish_testpypi

Then upload to PyPI:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=<pypi-api-token>
uv run poe publish_pypi

You can create API tokens in your account settings:

• TestPyPI: https://test.pypi.org/manage/account/token/
• PyPI: https://pypi.org/manage/account/token/