Command interfaces without ceremony

Turn Python functions into a polished CLI.

Vulcano is for the moment when a script becomes a tool. Keep your functions plain, register them with the app, and get an interactive REPL, one-shot argument mode, autocomplete, inline help, history, syntax highlighting, and nested command groups.

Python 3.10+Built for modern Python
prompt_toolkitInteractive shell foundation
Rich + PygmentsReadable command output

Problem specs

The command surface you usually postpone.

Spec 01

I have useful functions.

Register existing Python callables without rewriting them into a heavy command framework.

Spec 02

I need discoverability.

Help tables, command descriptions, argument inspection, and suggestions make the tool self-explaining.

Spec 03

I need an interactive mode.

History, completions, themes, and nested groups make repeated command work comfortable.

Spec 04

I still need shell mode.

Run commands directly from arguments, chain actions with and, and use dot paths for grouped commands.

Get to know Vulcano

A framework that stays close to your code.

Autocomplete

Command names and argument names are inferred from registered functions.

Inline help

Docstrings and descriptions become readable help screens.

Argument options

arg_opts suggests predefined values and quotes values with spaces.

Command chaining

Run multiple actions with and in REPL or argument mode.

Groups

Organize commands into nested sub-contexts with dot-path execution.

Source inspection

Append ? to a command to view highlighted source.

Quickstart

One file is enough to start.

pip install vulcano
from vulcano.app import VulcanoApp
from vulcano.themes import MonokaiTheme

app = VulcanoApp()

@app.command("hi", "Greet someone by name")
def salute(name, title="Mr."):
    return "Hi! {} {}.".format(title, name)

@app.command("greet", "Greet someone by role", arg_opts={"role": ["admin", "user", "guest"]})
def greet_by_role(name, role="user"):
    return "Hello, {} {}!".format(role.capitalize(), name)

if __name__ == "__main__":
    app.run(theme=MonokaiTheme)
python your_app.py hi name=David
python your_app.py greet name=David role=admin

Technical specs

Small surface, useful defaults.

AreaCapability
RuntimePython 3.10, 3.11, 3.12, and 3.13
InterfaceInteractive REPL and one-shot argument execution
ParsingFunction argument inspection and command parsing
UXAutocomplete, history, suggestions, help, syntax highlighting
OrganizationNested command groups and dot-path execution
PackagingPyPI package with a vulcano script entry point

Vulcano is under active development. Pin a version for production use while the API moves toward a stable 1.x release.