LaunchLine

A lightweight terminal launcher for interactive CLI tools. Define your frequently used commands in a TOML config file, then pick them from a fuzzy-searchable menu instead of remembering flags and paths.

Why

Switching between CLI tools — AI assistants, shells, dev utilities — means remembering commands, flags, working directories, and environment variables. LaunchLine puts them all in one menu so you press a number or type a few letters instead.

Features

• Fuzzy search — type any substring to narrow the list instantly
• Numbered shortcuts — press a digit to launch directly
• Per-entry environment and working directory — set once, forget forever
• Auto-restart or exit — configurable behavior after a tool exits
• Zero runtime dependencies — pure Python 3.12+, nothing to install beyond itself
• Auto-generated starter config — creates ~/.config/launchline/config.toml on first run if no config exists

Fuzzy search	Arrow-key navigation

Installation

From PyPI (recommended)

uv tool install launchline

Or with pip:

pip install launchline

From source

git clone https://github.com/mikejhill/launchline.git
cd launchline
uv tool install .

Run without installing

git clone https://github.com/mikejhill/launchline.git
cd launchline
uv sync --group dev
uv run launchline

Quick Start

1. Run launchline. If no config exists, a starter config is created at ~/.config/launchline/config.toml.
2. Edit the config to add your tools.
3. Run launchline again.

Override the config path:

# CLI flag (highest priority)
launchline --config ~/my-config.toml

# Environment variable
export LAUNCHLINE_CONFIG=~/my-config.toml
launchline

Resolution order: --config flag > LAUNCHLINE_CONFIG env var > default path.

Configuration Reference

Config file format is TOML. The file has an optional [settings] table and one or more [[entries]] tables.

[settings]

[[entries]]

Each [[entries]] table defines one launchable tool:

Validation Rules

• A root requires nonempty [[entries]] or a [provider] declaration.
• Every entry needs name and either command or menu.
• on_exit must be "restart" or "exit".
• args must be a list (not a bare string).
• env must be a TOML table (not a string or list).
• If working_directory does not exist at load time, it is silently reset to None (a warning is logged).

Example Config

[settings]
title = "My Tools"
on_exit = "restart"
show_exit = true
clear_on_launch = true
ghost_text = true
numeric_trigger = true

[[entries]]
name = "GitHub Copilot CLI"
command = "copilot"

[[entries]]
name = "Claude Code"
command = "claude"
description = "Anthropic coding agent"
working_directory = "~/projects"

[[entries]]
name = "PowerShell"
command = "pwsh"
args = ["-NoProfile"]
env = { TERM = "xterm-256color" }

Usage

Windows Terminal Integration

Add LaunchLine as a Windows Terminal profile to use it as your default launcher. The package bundles an icon that you can reference via launchline --icon-path:

// In your Windows Terminal settings.json → profiles.list
{
  "name": "LaunchLine",
  "commandline": "launchline",
  "startingDirectory": "%USERPROFILE%",
  // Run: launchline --icon-path
  "icon": "C:/Users/you/.local/lib/.../launchline/assets/launchline.ico"
}

Set it as the default profile to see the launcher every time you open a terminal.

Development

uv sync --group dev
uv run pytest
uv run ruff check .
uv run mypy src

License

MIT

See Also

• LaunchLine (Rust) — a Rust implementation with the shared configuration and keyboard contract, ships as a single native binary.

Compatibility and validation

Use launchline --check-config to validate configuration without opening the menu. Set NO_COLOR for a selection marker without ANSI color. See the compatibility matrix, reproducible test and performance results, and release readiness.

[provider]

The same table is accepted under entries.menu.provider. See the menu lifecycle and provider contract for nesting, caching, refresh/back behavior, limits, errors and examples.