comma-command

Run any command you have installed from any shell, as if it were a shell builtin:

$ gus, hello world
# → too talk gus -- hello world

Register an entry once. From then on, NAME, any words is the whole interface — no aliases to source, no shell hook, no TUI.

Install

$ uv tool install comma-command    # or: pipx install comma-command
$ comma init --write               # puts the shim directory on PATH
$ exec $SHELL                      # or open a new terminal

Quickstart

$ comma add gus -- too talk gus --
added gus, → too talk gus --

$ comma add pyi -- uv run ipython --
added pyi, → uv run ipython --

$ gus, hello world          # runs: too talk gus -- hello world
$ pyi, --pdb script.py      # runs: uv run ipython -- --pdb script.py
$ comma ls
gus,  too talk gus --
pyi,  uv run ipython --

comma add does two things: writes the entry to ~/.config/comma/config.toml and creates an executable named exactly gus, in ~/.local/share/comma/bin.

How it works

The shim is a multicall dispatcher — the same trick busybox and git use for subcommands, applied to names:

1. gus, is a symlink to the comma executable.
2. comma looks at argv[0], sees a trailing comma, strips it, and finds gus in the config.
3. It calls os.execvpe("too", ["too", "talk", "gus", "--", "hello", "world"]).

If the shim directory is not on PATH — a CI job, a container, a repo where nobody ran comma init — comma gus, hello world reaches the same dispatch path. comma takes NAME, rather than bare NAME so that a registered name can never collide with the management subcommands (ls, run, doctor, ...).

Because the final step replaces the process instead of spawning a child, the target command inherits the terminal, stdin, signals and job control directly, and its exit status reaches your shell unchanged. comma, adds no wrapping layer.

Why not the alternatives:

• Shell aliases/functions. gus, is not a portable function name in bash or fish, and functions only exist in interactive shells you have sourced.
• command_not_found_handle hooks. Bash-only, collides with distro handlers (Nix, Debian's package suggestion hook), and silently does nothing in non-interactive shells, sh -c, cron, or most editors' task runners.
• Shims on PATH. Work everywhere a real executable works, including xargs, find -exec, CI scripts, Makefiles and shell completion.

Configuration

~/.config/comma/config.toml — managed by comma, but hand-editable:

[commands.gus]
cmd = ["too", "talk", "gus", "--"]

# shorthand is fine too
[commands.pyi]
cmd = "uv run ipython --"

Arguments are appended verbatim, so -- at the end of cmd is the usual way to keep flags from being swallowed by the target's own option parser.

Commands

Names must be shell-safe words: letters, digits, ., _, +, -. The comma is added for you, so comma add gus, -- ... is rejected rather than silently creating gus,,.

Limits

• POSIX first. Windows needs a .cmd shim layer, which is not in 0.1.
• No per-command env/cwd yet; use cmd = ["sh", "-c", "..."] as an escape hatch.
• The comma-command crate on crates.io is a name reservation for a future native binary; the Python implementation is the one to install today.

Development

$ uv venv && uv pip install -e '.[dev]'
$ uv run pytest
$ uv run ruff check .

MIT licensed.