larpshell - use terminal with natural language

Why learn shell commands when you can just larp ts? Takuji and larptok approved.

---

larpshell translates natural language into shell commands using AI, then executes them in your terminal (not without asking for confirmation of course). You can also edit the commands before running, or ask for an explanation of what they do. Both prompt templates for command generation and explanation are customizable.

Usage Demo

Important

Review every generated command before you run it. larpshell asks first, but the command still executes on your machine.

What it does

• one-shot mode: larpshell show disk usage
• REPL mode: larpshell
• stdin mode: echo "show disk usage" | larpshell
• command explanation: larpshell explain df -h
• editable prompts for generation, explanation, and agent mode
• optional agent mode with built-in tools and MCP servers

Install

Requirements

Rust Language

From crates.io (recommended):

cargo install larpshell

From source:

curl -sSL https://raw.githubusercontent.com/uwuclxdy/larpshell/mommy/install.sh | sh

Packaged

Arch Linux

From AUR (bin; latest release, no Rust needed): yay -S larpshell

From AUR (git; latest commit): yay -S larpshell-git

Configure a provider

Run:

larpshell api

larpshell stores config in ~/.config/larpshell/config.toml.

Supported providers

Provider	Notes
Gemini	Free API key at aistudio.google.com/apikey
OpenRouter	Free models available with openrouter/auto (default, free models list)
Ollama	API key optional
OpenAI-compatible	any compatible API (custom base URL support)

Usage

One-shot

$ larpshell show disk usage
> df -h
Run this?
[Y/Enter] to execute, [E] to explain, [Arrow Up] to edit, [N] to cancel

Interactive REPL

$ larpshell
larpshell> show disk usage
> df -h
Run this?
[Y/Enter] to execute, [E] to explain, [Arrow Up] to edit, [N] to cancel

Stdin / pipe

echo "show disk usage" | larpshell

If piped input starts with /, larpshell treats it as a slash command.

Explain a command

$ larpshell explain df -h
> df -h
✅ Displays free disk space of mounted filesystems in a human readable format.
Run this?
[Y/Enter] to execute, [Arrow Up] to edit, [N] to cancel

Edit before running

Press Arrow Up at the confirmation prompt to resend the generated command into the input editor.

Agent mode

Agent mode lets the model gather context before it returns a final command.

Built-in tools:

• read_file
• list_files
• search_files
• run_command

Every tool call asks for confirmation before it runs.

Modes:

• larpshell agent off disables agent mode
• larpshell agent safe enables restricted tools
• larpshell agent on enables unrestricted agent tools

Safe mode keeps run_command on a read-only allowlist and blocks dangerous flags, shell metacharacters, and mutating git subcommands.

Example:

$ larpshell what's the largest file in this repo
  tool Allow listing files in .?
  result (14 lines)
  tool Allow running du -ah --max-depth=2?
  result (28 lines)
> du -ah . | sort -rh | head -n 1
Run this?
[Y/Enter] to execute, [E] to explain, [Arrow Up] to edit, [N] to cancel

MCP servers

larpshell loads MCP servers from ~/.config/larpshell/mcp.json.

{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--repository", "."]
    }
  }
}

Slash commands

Interactive mode supports:

• /api
• /agent [off|safe|on]
• /explain <command>
• /history [on|off]
• /prompt [system|explain|agent|agent-safe] [show|edit|reset]
• /help
• /quit
• /uninstall

In the REPL, ! <command> runs a shell command directly.

Prompt files and history

larpshell stores prompt templates in ~/.config/larpshell/:

• sys-prompt.md
• explain-prompt.md
• agent-prompt.md
• agent-safe-prompt.md

Use the CLI or slash commands to show, edit, or reset them.

Prompt history is on by default. Toggle it with larpshell history on|off or /history on|off.

Shell integration

On the first interactive run without a subcommand, larpshell tries to install shell integration automatically.

Current support:

• bash function in ~/.bashrc
• fish function in ~/.config/fish/functions/larpshell.fish
• bash, zsh, and fish completions

If setup changes your shell files, restart your shell or source the updated config.

The test suite builds the binary and runs it against mock provider servers. It does not need real provider credentials.

License

GPL-3.0