Hotkeys: ctrl vs. cmd
Hucksh has macOS, Linux, and Windows clients. As you may know, Macs have a “command” or “cmd” key in addition to “ctrl” and “opt” (aka “alt”). In general, if a shortcut on macOS uses the Cmd key, on Linux/Windows it will use Ctrl; ditto “opt” vs “alt”.
Overview
The gui starts with three tabs, DIRS, HIST, and a shell tab.
The shell tab is where you run commands.
The DIRS tab is the hucksh directory browser. You can navigate around your filesystem with the mouse or various hotkeys, go “back” and “forward” in your history, select files to easily copy their names to the clipboard, or edit them.
The HIST tab shows every directory you’ve ever visited in a shell tab. You can click on directories to display them in the DIRS tab, or move the selection caret up and down with Cmd-Up & Cmd-Down (Linux/Windows: Ctrl-P & Ctrl-N), or filter using the top textbox.
Running without a license: Trial Mode
If you haven’t installed a license (available here: https://huckridgesw.onfastspring.com/hucksh-license), the app will run in “trial mode”, which means it will only open a single top-level window, and only two shell tabs are allowed.
Navigating tabs
- Click on the tabs themselves to change tabs.
- Certain keys (typically Enter) on the DIRS or HIST tabs will switch back to the active shell tab (the one with a “*” next to its name).
- Click the “X” on the left side of a tab to close it. If there’s only one shell tab, it won’t have the “X”.
A shell tab takes a second or so before it becomes the “active” tab, or click the mouse anywhere in the window.
Tab bar hotkeys
| macOS | Linux/Windows | Meaning |
|---|---|---|
| Cmd-Shift-[ Cmd-{ | Ctrl-Shift-[ Ctrl-} | Activate tab to the left |
| Cmd-Shift-] Cmd-} | Ctrl-Shift-] Ctrl-} | Activate tab to the right |
| Cmd-1 | Ctrl-1 | Activate the DIRS tab |
| Cmd-2 | Ctrl-2 | Activate the HIST tab |
| Cmd-3 – Cmd-8 | Ctrl-3 – Ctrl-8 | Activate shell tabs 3-8 |
| Cmd-9 | Ctrl-9 | Activate the last shell tab |
| Cmd-T | Ctrl-T | Open a new shell tab |
| Cmd-W | Ctrl-W | Close the current shell tab Popped-out command: Close the window |
| Cmd-Shift-W | Ctrl-Shift-W | Close the whole window |
A note about shell tabs: In trial mode (running without a license installed), you only get two shell tabs.
Shell tab – running commands
Command entry overview
You enter commands at the bottom of a shell tab. Type in the command and press Enter to run it. Use regular cursor keys to move around and edit. You can select, cut, copy, and paste, and there’s a rudimentary undo/redo feature.
If a command is running and you want to start entering another one, press Cmd-Shift-& (macOS) or Ctrl-Shift-& (Linux/Windows).
Press Cmd-Up/Down (macOS only) or Cmd/Ctrl-P/N (all platforms) to go backwards & forwards in your command history.
See below for more hotkeys.
Interacting with running commands
Some of this is admittedly still suboptimal.
Once you’ve submitted a command, it starts in its own panel, with its own TTY and stdin & stdout. All “control characters” (Ctrl-C, etc) are sent to the running command as you’d expect. You can also press the “Cancel/INT/Kill” button to abort the command.
(Full disclosure: ^C and the “Cancel/INT/Kill” buttons don’t always work. Sometimes to abort something you just have to find the command’s pid and kill it. I’m still working on that.)
If you run a command that wants to read from the “controlling terminal” (like “sudo”, which wants to read your password, or “less”), the command will appear to just hang. Go to the terminal where you’re running the server and enter whatever it’s looking for. This is why it’s handy to run the server in a screen window, because you can reattach to it from anywhere. You can also run screen inside hucksh itself, and that will let you enter the password the normal way. Example: screen -dR hucksh.$HUCKSH_CMD_ID sudo <some-command>
The command panel has full xterm-256color terminal emulation, via https://github.com/HuckridgeSW/vt10x (forked from https://github.com/ActiveState/vt10x). The interaction between vt10x & hucksh is not yet perfect, but I’m working on it.
Command directories are clickable
Each command panel shows the directory the command was started in. You can click on any component of any of those directories to change the shell’s current directory to the clicked path. E.g. if you were in /home/you/some/directory and you ran some command and then you clicked on “you”, the shell’s current directory would switch to “/home/you”.
Command buttons
The buttons across the top of the command entry widget by default work on the last command in the tab. If a different command is selected (it’ll be highlighted with a red box), then they work on the highlighted command.
| Button | Meaning |
|---|---|
| Wrap/Nowrap | Wrap or don’t wrap long lines |
| Zoom | Open the command in a new full-window tab of its own |
| Popout | Open the command in a new top-level window |
| Hide/Unhide | Hide or unhide the output of the command |
| Remove | Remove the command from the tab (it’s still in the database will show up in history searches). |
| Copy cmd | Copy the command text to the system clipboard |
| Copy output | Copy the command output to the system clipboard |
| Copy both | Copy both the command and the output to the system clipboard |
| Edit output | Open the command output in a local editor (requires some configuration) |
| Paste cmd | Paste the command text into the command textbox (but don’t run it) |
| cd & run | cd to the directory of the selected command and run the command again |
In a popped-out command, the Cmd/Ctrl-W key will close the window.
You can “popout” a command more than once. This can be handy to look at different parts of the output of the command at the same time.
Command entry hotkeys
| macOS | Linux/Windows | Meaning |
|---|---|---|
| Enter | Enter | Run the command in the given directory |
| Cmd-Up Cmd-P | Ctrl-P | Display the previous command in the editor |
| Cmd-Down Cmd-N | Ctrl-N | Display the next command in the editor |
| Cmd-R | Ctrl-R | Re-run the previous command (ignores the currently entered command) |
| Cmd-E | Ctrl-E | Edit the command in an external editor (requires some configuration) |
Editing the command in an external editor writes the current command to a temp file, opens the tempfile in an editor (via “hucksh-edit local /path/to/file”), waits for the editor to exit, and replaces the current contents of the command editor with the contents of the tempfile.
The external editor is independent of the hucksh gui. If you so desire, you can go on and run other commands and generally use the gui in the usual way. When the external editor exits, the above process continues, even if you’ve started several other commands in the meantime.
Shell tab hotkeys
| macOS | Linux/Windows | Meaning |
|---|---|---|
| Enter | Enter | Run the command |
| Shift-Enter | Shift-Enter | Insert a newline into the current command |
| Cmd-R | Ctrl-R | Re-run the selected command, in the same directory |
| Cmd-3…8 | Ctrl-3…8 | Switch to the given shell tab, 3-8 |
| Cmd-9 | Ctrl-9 | Switch to the last shell tab |
| Cmd-U (see warning below) | Ctrl-U | Go up one directory |
| Cmd-/ | Ctrl-/ | Open the command history search panel (see below) |
| Cmd-Home | Ctrl-Home | Scroll to the top |
| Cmd-End | Ctrl-End | Scroll to the bottom |
| Cmd-PgUp | Ctrl-PgUp | Scroll up one page |
| Cmd-PgDn | Ctrl-PgDn | Scroll down one page |
| Cmd-Shift-Up | Ctrl-Shift-Up | Select the previous command, sort of |
| Cmd-Shift-Down | Ctrl-Shift-Down | Select the next command, sort of |
| Cmd-Shift-& | Ctrl-Shift-& | Display the command editor window (“background” the current command) |
| Cmd-Shift-D | Ctrl-Shift-D | Show the current directory in the DIRS tab |
| Cmd-Shift-C | Ctrl-Shift-C | Copy the current command to the system clipboard, in the cmd editor, or for the currently-highlighted command. |
| Cmd-Shift-E | Ctrl-Shift-E | Edit the current command output in an external editor |
| Ctrl-C | Ctrl-C | Clear the command editor |
| Ctrl-D | Ctrl-D | Display or dismiss the completion widget |
| Cmd-T | Ctrl-T | Open a new tab in the current directory |
| Cmd-W | Ctrl-W | Close the current tab (except the last tab), or “zoomed” command, or popout window. |
| Cmd-Shift-W | Ctrl-Shift-W | Close the current window |
Shell completion panel
The completion widget will complete environment variables, filenames, command names, and function names.
| macOS | Linux/Windows | Meaning |
|---|---|---|
| Ctrl-D | Ctrl-D | Display or dismiss the completion widget Note that all platforms use the actual Ctrl key. |
| ESC | ESC | Dismiss the completion widget |
| Cmd-R | Ctrl-R | Refresh the current completions |
| Tab | Tab | Move to the next completion |
| Shift-Tab | Shift-Tab | Move to the previous completion |
| Enter | Enter | Choose the current completion |
And of course you can click on any completion to choose it directly.
Shell history search panel
The history panel shows every command you’ve ever run and the directory you ran it in. Typing text into the textbox at the bottom filters the list to commands matching the given regex.
If there’s text in the command entry textbox, the history will be pre-filtered using the given text as a regex to be searched for.
| Button | Meaning |
|---|---|
| Copy | Copy the command into the system clipboard |
| Paste | Paste the command into the hucksh command editor (without overwriting what’s there) |
| cd & paste | CD to that command’s directory and paste the command into the hucksh command editor |
| cd & run | CD to that command’s directory and run the command |
Hotkeys
| macOS | Linux/Windows | Meaning |
|---|---|---|
| ESC | ESC | Clear the filter box, or (if already empty) dismiss the search panel |
| Enter | Enter | Dismiss the panel & set the command editor to the current command |
| Cmd-Enter | Ctrl-Enter | Like pressing “cd & run” (see above) |
| Ctrl-C | Ctrl-C | Clear the filter box |
| Cmd-Up Cmd-P | Ctrl-P | Select the previous command |
| Cmd-Down Cmd-N | Ctrl-N | Select the next command |
| Cmd-Home | Ctrl-Home | Scroll to the top |
| Cmd-End | Ctrl-End | Scroll to the bottom |
| Cmd-PgUp | Ctrl-PgUp | Scroll up one page |
| Cmd-PgDn | Ctrl-PgDn | Scroll down one page |
DIRS tab – browsing directories
- Type text into the top textbox to filter via regex.
- Press the <- / -> buttons to go forward or backward in your directory history.
- Press the .. button to go up one directory.
- Press the “cd” button to change to the previously-active shell tab and CD to that directory.
- Click directories to navigate into them. You can click anywhere on the line (except the selection box), you don’t have to click right on the directory name.
- Select directories & files via the selection boxes, and then press the “Copy” or “Edit” buttons (which are only displayed once you’ve selected some files.)
- The “Copy” button copies the selected filenames to the clipboard.
- The “Edit” button edits the selected files in a local editor.
- Click the Size / Time / Name buttons to change how the listing is sorted.
- Click any component of the diplayed directory (next to the “cd” button) to change to that directory. E.g. for /home/you/some/directory, click on “you” to change to /home/you.
- Press Cmd/Ctrl-D/F/O to show or hide Directories, Files, and dOtfiles (e.g.
.huckshrc). If you’re hiding “dotfiles”, all directory entries starting with a.will be hidden, whether they’re directories or files.
Text box filtering
- As mentioned above, type text into the box to filter via the given regex.
- If you filter down to where there’s only a single directory that matches your regex (even if several other non-directories also match), press “/” to navigate into that directory.
- If you press “/” with no text, this navigates directly to the root directory.
“Navigation mode”
Press Cmd-M (Linux/Windows: Ctrl-M) to enter navigation mode. This displays a new “Nav” column in the directory listing, with various automatically generated shortcuts for each directory. Press the given letter to navigate into that directory.
Press ESC or Cmd-M (Linux/Windows: Ctrl-M) again to exit navigation mode. Leave the DIRS tab and then returning also disables navigation mode.
Navigation mode shows only directories and hides all non-directories.
DIRS tab Hotkeys
| macOS | Linux/Windows | Meaning |
|---|---|---|
| Cmd-1 | Ctrl-1 | Switch to the DIRS tab |
| ESC | ESC | Turn off Navigation mode, or clear the current regex |
| Cmd-M | Ctrl-M | Enter or leave Navigation mode |
| Cmd-R | Ctrl-R | Refresh the directory listing |
| Cmd-D | Ctrl-D | Show or hide directories |
| Cmd-F | Ctrl-F | Show or hide files |
| Cmd-O | Ctrl-O | Show or hide “dotfiles” (.*) |
| Cmd-U (see warning below) Cmd-Up | Ctrl-U | Go up one directory |
| Cmd-Left Cmd-Down | Ctrl-Left | Go backwards in history |
| Cmd-Right | Ctrl-Right | Go forwards in history |
| Enter Cmd-Enter | Enter Ctrl-Enter | Switch to the current shell tab and CD to the current directory |
| Cmd-Home | Ctrl-Home | Scroll to top |
| Cmd-End | Ctrl-End | Scroll to end |
| Cmd-PgUp | Ctrl-PgUp | Page up |
| Cmd-PgDn | Ctrl-PgDn | Page down |
| Cmd-Shift-C | Ctrl-Shift-C | Copy the current directory name to the system clipboard |
| Cmd-Shift-V | Ctrl-Shift-V | CD to the directory in the system clipboard |
| Cmd-Shift-Opt-C | Ctrl-Shift-Alt-C | Copy filenames of selected items to the system clipboard |
| Cmd-Shift-N | Ctrl-Shift-N | Toggle name sort |
| Cmd-Shift-T | Ctrl-Shift-T | Toggle time sort |
| Cmd-Shift-S | Ctrl-Shift-S | Toggle size sort |
| Cmd-Shift-A | Ctrl-Shift-A | Toggle on/off all file selections |
| Cmd-Shift-E | Ctrl-Shift-E | Edit selected files |
The regexp textbox has several of its own hotkeys, not mentioned here.
HIST tab – viewing historical directory usage
The HIST tab lists all the directories you’ve ever used, in any session, where “used” means:
- Pressed “Enter” on it in the DIRS tab to CD to that directory in a shell tab
- CDed to it in a shell tab (that is, it was the shell’s $PWD at the end of a command)
It’s updated immediately in all clients, so if you use a directory in one client it should immediately show up in the HIST tab of all clients. (This is most obvious when you sort by “last visited”.)
HIST tab usage
- Press enter to show the selected directory in the DIRS tab
- Click on a displayed directory to open it in the DIRS tab
- Type text into the top textbox to filter the directories via regex
- Click the Uses / Dir / Last visit buttons to change the sorting
HIST tab hotkeys
| macOS | Linux/Windows | Meaning |
|---|---|---|
| Cmd-2 | Ctrl-2 | Switch to the HIST tab |
| Enter | Enter | Open the selected directory in the DIRS tab |
| ESC | ESC | Clear the current regex |
| Cmd-Shift-D | Ctrl-Shift-D | Toggle sort by directory name |
| Cmd-Shift-L | Ctrl-Shift-L | Toggle sort by last visit |
| Cmd-Shift-U | Ctrl-Shift-U | Toggle sort by uses |
| Cmd-Home | Ctrl-Home | Scroll to top |
| Cmd-End | Ctrl-End | Scroll to end |
| Cmd-PgUp | Ctrl-PgUp | Page up |
| Cmd-PgDn | Ctrl-PgDn | Page down |
| Cmd-Up Cmd-P | Ctrl-P | Move selection bar up |
| Cmd-Down Cmd-N | Ctrl-N | Move selection bar down |
| Cmd-Shift-C | Ctrl-Shift-C | Copy the selected directory to the system clipboard |
| Cmd-Shift-V | Ctrl-Shift-V | Open the directory in the system clipboard in the DIRS tab |
Tip: Note that Enter here opens the selected directory in the DIRS tab, and Enter in the DIRS tab will switch to the current shell tab and CD to that directory. So from the HIST tab, press Enter twice to switch to the current shell tab & CD to that directory.
Cmd-U Warning: If you’re on a Mac, in a VirtualBox VM, and you press Cmd-U, this is the default VirtualBox hotkey to shutdown the VM. This can be annoying, to say the least.