tutr - Terminal Utility for Con(T)extual Responses

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

Documentation

Docs website: https://spi3.github.io/tutr/index.html

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/spi3/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. xAI
  5. Ollama (local, no API key needed)

  Enter choice (1-5): 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.

To re-run or modify configuration at any time:

tutr-cli configure

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

Configure Command

Use configure to update provider/model selection and config flags.

Interactive wizard:

tutr-cli configure

Non-interactive examples:

tutr-cli configure --provider openai --model openai/gpt-4o --show-explanation
tutr-cli configure --provider anthropic --model anthropic/claude-sonnet-4-6
tutr-cli configure --provider ollama --ollama-host http://localhost:11434
tutr-cli configure --disable-update-check
tutr-cli configure --clear-api-key

Security note: avoid passing secrets via --api-key because CLI args can be exposed in shell history and process listings. Prefer interactive tutr-cli configure prompts or provider API key environment variables.

Configure Flags

Flag	Description
--interactive	Run the interactive wizard (default when no other flags are given)
--provider <name>	LLM provider (anthropic, gemini, ollama, openai, xai)
--model <id>	Model ID in LiteLLM format (e.g. openai/gpt-4o)
--api-key <key>	Store a provider API key in config (not recommended — may leak via shell history)
--clear-api-key	Remove the stored API key from config
--ollama-host <url>	Set Ollama host URL (e.g. http://localhost:11434)
--clear-ollama-host	Remove the stored Ollama host from config
--show-explanation	Enable explanation output by default
--hide-explanation	Disable explanation output by default
--enable-update-check	Enable periodic update checks (default)
--disable-update-check	Disable periodic update checks
--allow-execute	In shell mode, allow prompting to auto-run tutr suggestions (default)
--no-execute	In shell mode, never prompt to auto-run tutr suggestions

Update Checks

tutr periodically checks PyPI for newer versions (at most once every 24 hours). When an update is available, it prints a notice to stderr with the suggested update command. In an interactive terminal it also offers to run the update immediately.

The check runs in the background and times out after 1.5 seconds so it never slows down normal usage. A timestamp cache is stored at ~/.tutr/update-check.json.

To disable update checks permanently:

tutr-cli configure --disable-update-check

Or suppress checks for a single session:

TUTR_UPDATE_CHECK=0 tutr ...

Data sent to model providers

When tutr calls an LLM API, it may send:

• Your natural-language query.
• Command reference context collected from <command> --help and/or man <command>.
• Basic system information (for example platform/OS details).
• In shell wrapper mode, up to 2048 characters of recent terminal output after a failed command.

If you use remote providers, treat this information as data transmitted to that provider. Avoid including secrets in commands, queries, or terminal output.

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	—
XAI_API_KEY	xAI API key	—
OLLAMA_HOST	Ollama host URL override	http://localhost:11434
TUTR_UPDATE_CHECK	Enable (1/true) or disable (0/false) update checks	true
TUTR_SHELL	Override wrapper shell detection (bash, zsh, pwsh, or powershell)	auto-detected
NO_COLOR	Disable ANSI color output (any value; follows no-color.org)	unset

You can edit settings with tutr-cli configure or directly in ~/.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 .