Edit shell commands by their parts, not by moving the cursor around.
You run the same commands over and over with small differences:
kubectl describe pod my-app-xxx -n production
git tag -a "v0.39.2" -m "v0.39.2"
docker logs -f --tail=100 my-container
ssh -i ~/.ssh/id_ed25519 user@server01
curl -H "Authorization: Bearer $TOKEN" https://api.example.com
find /var/log -name "*.log" -mtime -1
tcpdump -i eth0 host 10.0.0.1 -nnHistory search gets you close, but then you still have to edit the namespace, the pod name or a flag by hand. rx splits the command in your prompt into slots (arguments and flags) and lets you change each one from a list of suggestions.
- Type or recall a command, e.g.
find /var/log -name "*.log" -mtime -1. - Press Ctrl-X Ctrl-X. A small editor opens below your prompt.
- Press Tab to move between slots. Type a value, or pick one of the suggestions with ↓.
- Press Enter. The edited command is put back in your prompt. Press Enter again to run it.
Suggestions come from:
- Your shell history: values you've used before, most frequent and recent first.
- Shell completion: the same values you'd get from pressing Tab in zsh, bash or fish, such as namespaces, git branches or ssh hosts.
- Plugins: small YAML files that add shortcuts and extra knowledge about a command.
rx supports zsh, bash 4.1 or newer and fish 3.4 or newer, on Linux and macOS.
Download the latest release for your platform from GitHub Releases and put rx on your PATH:
curl -fsSL "https://github.com/amimof/rx/releases/latest/download/rx_$(uname -s)_$(uname -m).tar.gz" | tar -xz rx
sudo install rx /usr/local/bin/
rx --versionEach release also has a checksums.txt to verify the download. To build from source instead, run go install github.com/amimof/rx/cmd/rx@latest.
Then add the line for your shell and open a new shell:
eval "$(rx init zsh)" # ~/.zshrc
eval "$(rx init bash)" # ~/.bashrc
rx init fish | source # ~/.config/fish/config.fishmacOS ships bash 3.2 as /bin/bash, which is too old. Use a newer bash, e.g. from Homebrew (brew install bash). With bash, rx runs history -a before it opens, so it sees the commands of the current session. In bash this appends them to $HISTFILE earlier than bash would by itself.
Check that everything is set up:
rx-doctor| Key | Action |
|---|---|
Tab / Shift+Tab |
Next / previous slot |
| Type | Type a value. Matching suggestions are listed, but only an exact match is picked, so what you typed is used. On + flag, the best match is picked |
↑ ↓ |
Pick a value, ↑ from the top goes back to what you typed |
Ctrl+N / Ctrl+P |
Same as ↓ / ↑ |
Enter |
Put the command back in the prompt |
Ctrl+E |
Put the command back in the prompt and run it |
Ctrl+S |
Cycle the suggestion source: all, then each enabled source the slot has |
Ctrl+D |
Remove the current slot |
Ctrl+Q |
Link the slot to the other slots with the same value |
Ctrl+F |
Zoom in on the slot to edit one part of its value, e.g. a URL's port |
Alt+I |
Insert: edit the slot's value, or the zoomed part, in place with a cursor |
Ctrl+Y |
Quote the slot's value: single quotes, double quotes, then only if needed |
Ctrl+Z |
Undo the last edit, along with what rules did after it |
Ctrl+U / Ctrl+W |
Clear the search |
Esc |
Clear the search, press again to cancel |
Ctrl+C |
Cancel |
Ctrl+<key> / Alt+<key> |
Plugin shortcuts, e.g. Ctrl+A toggles --all-namespaces for kubectl |
The last slot, + flag, lets you add a new flag. All of these keys except plugin shortcuts can be changed in the config file.
rx reads ~/.config/rx/config.yaml (or $XDG_CONFIG_HOME/rx/config.yaml, or the file given with --config). Every setting is optional:
key: "^X^X" # key that opens rx, in caret notation
log: ~/.cache/rx/rx.log # widget log file
prompt: "❯" # symbol before the command in the editor; "" for none
complete: auto # completion sources, or a list of them; plugins may replace it
rules: live # when plugin rules run: live, commit or off
focus: last # start on the slot last edited, for commands whose plugin sets no focus
focus_last: true # remember the slot last edited per command; false turns "last" off everywhere
legend: true # show the key legend below the editor
keys: # editor keys; a list replaces that action's defaults
accept: [enter]
run: [ctrl+e] # accept, then run the command
cancel: [ctrl+c]
back: [esc] # clear the search, press again to cancel
up: [up, ctrl+p]
down: [down, ctrl+n]
next-slot: [tab]
prev-slot: [shift+tab]
source: [ctrl+s]
drop: [ctrl+d]
clear: [ctrl+u, ctrl+w]
undo: [ctrl+z]
link: [ctrl+q] # edit every slot with the focused slot's value
zoom: [ctrl+f] # edit one part of the focused value
insert: [alt+i] # edit the focused value in place with a cursor
quote: [ctrl+y] # cycle how the focused value is quoted
theme: # editor colors; a role replaces that role's default
flag: "#5f87ff" # a string sets only the text color
value: { fg: 2, bold: true }
sel: { fg: "#ffaf00", bg: 236, bold: true }
border: { fg: 8 } # instead of faintKeys are named like ctrl+e, alt+y, shift+tab, enter, esc, up. An empty list (drop: []) unbinds an action. Single characters and space can't be bound, since they type into the search. Run rx doctor to check the file.
link edits repeated values together. In git tag -a v0.1.0 -m v0.1.0, Ctrl-Q on either v0.1.0 links it to the other one, which is then underlined. What you type or pick shows up in both, and Tab, Enter or Ctrl-E writes it to both as one edit. ↑/↓, Ctrl-U and Ctrl-S keep the link; any other key, or Ctrl-Q again, ends it without changing the other slots.
Typing replaces the whole value of a slot. To change only part of it, press Ctrl-F (zoom). In curl https://localhost:7878/compute/v2/servers, the URL splits into scheme, host, port and path segments, and the first part, https, is highlighted. Tab/Shift-Tab move between parts, wrapping around at the ends, and what you type or pick replaces only the highlighted one. To change the port, press Ctrl-F, Tab twice, type 8080 and press Ctrl-F again.
- The list shows the values the same part had in this slot's history, e.g. the other ports you used in curl URLs.
- Ctrl-F zooms out, writing the value to the slot as one edit. Enter does the same; a second Enter accepts the command. Ctrl-E writes it and runs the command.
- Ctrl-Z undoes the last part you changed. Esc clears what you typed; pressed again, it leaves zoom without changing the slot.
rx recognises URLs (scheme, user, host, port, path segments, query parameters, fragment), [user@]host[:port], key=value, comma lists and slash paths. Anything else is split on / : = , @ ? & ; and spaces. A value with only one part can't be zoomed in on.
To change a few characters without retyping the value, press Alt-I (insert). The focused value, or the zoomed part, is loaded into the search with a cursor at the end, and readline keys edit it in place. In curl https://host:5000/v3/identity_providers/spoke-01/protocols/openid/auth, turning spoke-01 into spoke-cluster-01 is Alt-I, Alt-B five times, Alt-F, then typing -cluster and pressing Enter. Zoomed in on spoke-01, it is Alt-I, Ctrl-A, Alt-F, -cluster, Enter.
| Key | Action |
|---|---|
← → / Ctrl+B Ctrl+F |
Move one character |
Home End / Ctrl+A Ctrl+E |
Move to the start / end |
Alt+B Alt+F / Alt+← Alt+→ |
Move one word. Words are letters and digits, so -, /, . and _ end them |
Backspace / Delete, Ctrl+D |
Delete before / at the cursor |
Ctrl+W, Alt+D |
Delete the word before / after the cursor |
Ctrl+U / Ctrl+K |
Delete to the start / end |
↑ ↓ |
Pick a suggestion; the next key edits it instead of the typed text |
Alt+I / Enter |
Apply the edit and leave insert mode. Zoomed in, it is written to the part |
Tab / Shift+Tab |
Apply the edit and move to the next / previous slot or part |
Esc |
Leave insert mode without applying the edit |
These keys win over their usual actions and plugin shortcuts, which do nothing until you leave insert mode. Suggestions are still filtered by the text. Only values can be edited; + flag and flags without a value have none.
Ctrl-Y (quote) changes how the focused value is quoted, as one edit: 'single', then "double", then only if needed (plain, or 'a b' for a value with spaces). A style that would write the value the same way is skipped, e.g. "only if needed" for a b. A value with ! is never double-quoted, since bash and zsh would expand it from history. A value you typed or picked is applied first.
rx keeps a value's quoting when you edit it: -m "msg" becomes -m "new", not -m new. A value with an expansion such as $NS is quoted as written, so '$NS' and "\$NS" no longer expand it.
Theme roles are head (the command word), flag, value (a flag's value), arg (positional arguments), sel (the selected candidate), spinner (shown while candidates load), dim (descriptions, status and the help line), err, border, prompt, focus (the = between a focused flag and its value) and link (slots linked to the focused one). A role takes fg and bg colors, either an ANSI color number 0–255 or hex #rgb/#rrggbb, and bold, italic, faint, underline and reverse. Roles you don't list keep their default look. The focused slot is always shown reversed. Hex colors are approximated on terminals with fewer colors, and NO_COLOR turns colors off.
Environment variables override the file: RX_KEY, RX_LOG, RX_PROMPT, RX_RULES, RX_FOCUS, RX_FOCUS_LAST, RX_LEGEND, and RX_COMPLETE and RX_KEYS_<ACTION> with a comma-separated list, e.g. RX_COMPLETE=history,shell or RX_KEYS_NEXT_SLOT=tab,ctrl+b. The theme can only be set in the file.
key and log are baked into the widget by rx init, so changes take effect in new shells. To use a different key than Ctrl-X Ctrl-X without the config file, set RX_KEY before the eval line, or call rx-bind after it. The key is written in caret notation (^X^X, ^[r for Alt+r), which every shell accepts. bash also takes readline syntax (\C-x\C-x), and fish its own escapes (\cx\cx) and, from fish 4, key names (ctrl-x,ctrl-x). The default replaces the exchange-point-and-mark binding of zsh and bash in emacs mode; pick another key if you use it.
RX_KEY='^[r' # Alt+r
eval "$(rx init zsh)"In bash, rx is bound in the emacs, vi-insert and vi-command keymaps through a readline macro. That is how Ctrl+E can run the command as if Enter was pressed: it uses the internal sequences \C-x\C-^e and \C-x\C-^a.
In fish, rx is bound in the default and insert modes, which cover emacs and vi key bindings. fish binds a single Ctrl-X to copy to the clipboard. That still works with the default key, but fish waits for its key sequence timeout first (fish_sequence_key_delay_ms) in case a second Ctrl-X follows. rx loads aliases made with alias. Abbreviations need no support, since fish expands them before rx sees the command.
Plugins are optional YAML files that describe a command: which flags take values, which flags cancel each other out, one-key shortcuts, and rules that adjust the command as you edit it. rx ships with plugins for kubectl, git and curl (Ctrl+X cycles the HTTP method). You can add your own in ~/.config/rx/plugins/.
name: kubectl
match: { command: kubectl, aliases: [k] }
flags:
- { name: namespace, short: n, takes: value, mutex: [all-namespaces] }
- { name: all-namespaces, short: A, takes: none, mutex: [namespace] }
- { name: output, short: o, takes: value, values: [wide, yaml, json, name] }
transforms:
- { key: ctrl+a, op: toggle, flag: all-namespaces, desc: "all namespaces" }
- { key: ctrl+o, op: cycle, flag: output, desc: "cycle output" }A transform key is ctrl+<letter>, alt+<char>, or a bare character, which means alt+<char>. Plugin shortcuts take precedence over the editor's own keys, so avoid ctrl+ keys you use in the editor (by default ctrl+c, d, e, f, n, p, q, s, u, w, y and z). ctrl+i and ctrl+m can't be used, since terminals send them as Tab and Enter.
A cycle transform steps through the transform's values, or else the flag's or positional's values. If neither has any, rx cycles through the candidates the editor would list for that slot: history first, then completions. Cycling focuses the slot and selects its new value in the list.
A focus transform jumps to a slot so you can search its candidates and replace the value, adding the slot if the command doesn't have it yet. In kubectl, Ctrl+G jumps to the resource name.
Use focus: to choose which slot the editor starts on. It takes a positional name, pos:N, or a flag (namespace, --namespace, -n), or a list of these. The first one present in the command wins. Positionals declared in the plugin can always be focused, even before they're typed. Flags that aren't in the command are skipped. Without a match, rx starts on the first flag that takes a value.
The entry last is the slot you last edited in that command, remembered across sessions in ~/.cache/rx/focus.json. It is saved when you accept with Enter or Ctrl-E, not when you cancel. If you didn't edit anything, the slot focused at the end is saved. Memory is per command name, so after changing -X POST in curl -I -X POST http://localhost:7878 -k, the next curl you open starts on -X again. If the command has no such slot, the next entry is tried. All bundled plugins use focus: last. For commands without a plugin, or whose plugin sets no focus, turn it on with focus: last in the config file. focus_last: false (or RX_FOCUS_LAST=false) turns it off everywhere, including in plugins: last entries are skipped, and nothing is read from or saved to focus.json.
name: curl
match: { command: curl }
focus: [last, request] # the slot last edited, else -Xname: flux
match: { command: flux }
positionals:
- { index: 0, name: subcommand }
- { index: 1, name: kind }
focus: kind # `flux get kustomization` starts on "kustomization"name: find
match: { command: find }
focus: [-name, -type] # `find . -name "*.txt" -type d` starts on "*.txt"Check your plugin with rx plugins lint my-plugin.yaml.
A rule is a conditional transformation: when an edit makes its conditions hold, it changes other slots to match. The kubectl plugin's rule turns kubectl get pods my-pod -n default into kubectl logs my-pod -n default when you change get to logs, because logs takes the pod name without the resource. The curl plugin's rule adds -d '{}' when the method becomes POST, PUT or PATCH. The editor shows what a rule did below the list.
The rules setting in the config file decides when rules run:
| Value | Rules run |
|---|---|
live (default) |
as you type or move through the list. The preview and the rule notice show the result right away, e.g. typing logs shows kubectl logs my-pod -n default, and Backspace brings pods back. Nothing changes until Tab, Enter or Ctrl+E commits the value, and then the command is exactly what the preview showed. On + flag, only a fully typed flag name (--json, -d) or one picked with ↑/↓ triggers rules. |
commit |
when a value is committed with Tab, Shift+Tab, Enter or Ctrl+E |
off |
never |
Plugin shortcuts and Ctrl+D change the command directly, so with live or commit they run rules at once.
Rules remember the command from before they changed it. When their conditions stop holding, they put it back: change logs back to get and pods returns in front of the pod name, written as you typed it. Changes you made yourself are kept. If you rename the pod, edit the body or add the resource back yourself, the rule leaves your version alone, and a slot you delete isn't added again. Rules that already hold when rx opens don't fire, so opening rx never changes the command. Ctrl+Z undoes an edit together with what the rules did after it.
values: # spellings conditions treat as the same value
resource:
pod: [po, pods]
rules:
- name: logs-removes-resource
when: # one condition, or a list that must all hold
- argument: { name: subcommand, equals: logs }
- argument: { name: resource, equals: pod } # also matches po and pods
- argument: { name: name, exists: true }
then: # one action, or a list
- remove: { argument: resource }
- remove: { flag: output }
- name: post-adds-body # in curl's plugin
when:
flag: { name: request, in: [POST, PUT, PATCH] }
then:
add: { flag: data, value: "{}", unless_present: true }- Conditions test one slot: a positional by its name (
argument:) or a flag by its long name (flag:), with exactly one check:exists: true|false,equals,in(any of a list) ormatches(a regular expression).not:negates another condition. A flag given more than once matches if any of its values does. - Actions change one slot each:
addadds a flag or argument. A flag is added again if it's already there, since flags like-Hrepeat; an argument that's already there gets the value. Withunless_present: true, a slot that has a value is left alone. An argument added without a value becomes an empty slot that the editor focuses.removeremoves a flag or argument. The arguments after a removed one move up a position, so the pod name takes the resource's place.setsets a value, adding the slot if it's missing.
- Values are Go templates over the command's slots by name, as in providers (
{{.name}},{{default "default" .namespace}}). - A rule is judged without its own changes, so removing the resource it checked doesn't undo it. Rules that keep undoing each other stop after 10 rounds.
Positionals are not yet scoped to subcommands. kubectl logs my-pod as typed has my-pod in the resource slot, which is why the rule needs a name. rx rules -- 'k get pods my-pod' prints each rule, whether it holds and the command it would produce.
Candidates come from these sources:
| Source | Values |
|---|---|
history |
values used for the slot in your shell history |
spec |
the plugin's values |
provider |
the plugin's providers |
cli |
the command's own completion, for commands built with a supported CLI framework |
shell |
your shell's completion, as Tab would (in bash, without descriptions, which bash completion doesn't have) |
complete: picks the enabled sources, either one source or a list of them. auto, the default, enables all of them, and none enables none. Set it in the config file for every command, or in a plugin for that command. A plugin's complete: replaces the config file's.
complete: [history, spec, provider, cli] # kubectl: skip the shell
cli: cobraThe cli source runs the command's own completion through the protocol of the framework it is built with:
| Framework | Protocol |
|---|---|
| cobra (Go) | cmd __complete <args> |
| clap (Rust) | COMPLETE=fish cmd -- cmd <args>, from clap_complete::CompleteEnv |
rx detects the framework from the command's completion function in zsh, bash or fish, so it never runs a command that may not support the protocol. A plugin can set cli: to cobra or clap to skip detection, which also makes cli work outside the shell widget, e.g. in rx complete. With cli enabled, rx uses the command's own completion when it knows the framework, and asks the shell otherwise. If the command turns out not to speak the protocol, rx falls back to the shell for the rest of the session.
Only clap programs that use CompleteEnv with its default COMPLETE variable (like jj) have a protocol rx can call. Many Rust tools ship static completion scripts instead, which shell keeps handling.
In the editor, Ctrl+S switches to a single source for the rest of the session. Only enabled sources the slot has are offered, and cli only for commands whose framework rx knows.
- Run
rx-doctorin your shell to see which keys are bound and whether rx can find your history. - bash: the widget is built on readline's
bind -x. Line editors that replace readline, such as ble.sh, are untested. - fish: rx sees the commands of the current session only if fish writes history, which it doesn't in private mode (
fish --private). - If something goes wrong, rx shows a message below the prompt. More detail is in
~/.cache/rx/rx.log.
Issues and pull requests are welcome. Please open an issue before starting on larger changes. See CONTRIBUTING.md for how to build, test and add support for another shell.
