Andy Dixon
b6a7d51ddd
Bump the workspace to 3.0.1 and bring the user guide up to date: an RDP chapter, shell integration and inline images, SSH certificates and CAs, known_hosts import/export, stored credentials and master password change, profile sync (replacing the Alchementary Link migration chapter), the Diagnostics tab and log, and refreshed screenshots throughout. The welcome screen's protocol line now lists RDP.
265 lines
13 KiB
TeX
265 lines
13 KiB
TeX
\guidepart{violet}{Work faster}{Work faster}
|
||
{Fewer clicks, less typing, more getting on with it.}
|
||
{\partitem{\iSplit}{Tabs and split panes}
|
||
\partitem{\iKeyboard}{Terminal superpowers}
|
||
\partitem{\iWand}{Never type it twice}
|
||
\partitem{\iFolder}{Files: SFTP and drag-and-drop}
|
||
\partitem{\iArrows}{Port forwards}
|
||
\partitem{\iFilm}{Recordings}}
|
||
|
||
% =========================================================================================
|
||
\chapter{Tabs and split panes}\label{ch:tabs}
|
||
\chapmeta{4 minutes}{You'll juggle a dozen sessions without losing any of them}
|
||
|
||
\begin{tldr}
|
||
Right-click a tab for everything. \keys{\mod+Shift+D} splits right, \keys{\mod+Shift+E} splits down.
|
||
\keys{\mod+1} to \keys{\mod+9} jump straight to a tab.
|
||
\end{tldr}
|
||
|
||
\section{Tabs}
|
||
|
||
\begin{description}
|
||
\item[Move] Drag tabs about, or right-click\then\ui{Move Left} / \ui{Move Right}.
|
||
\item[Pin] Right-click\then\ui{Pin}. Pinned tabs stay at the front.
|
||
\item[Rename] Right-click\then\ui{Rename}. ``prod DB, DON'T TOUCH'' is a perfectly valid tab name.
|
||
\item[Duplicate] Opens another session to the same profile.
|
||
\item[Reconnect] Does what it says.
|
||
\item[Peek] Hover a tab for its name, host, state and when it connected.
|
||
\item[Close] The \ui{×}, \keys{\mod+W}, or right-click\then\ui{Close}. Connected tabs ask first (you can turn that
|
||
off in Settings).
|
||
\item[Switch] \keys{\mod+Tab} and \keys{\mod+Shift+Tab}, or \keys{\mod+1} to \keys{\mod+9}.
|
||
\end{description}
|
||
|
||
Lots of tabs? Scroll the tab strip with your mouse wheel or trackpad. Quit with a dozen open and they're all back next
|
||
time: \ui{Restore tabs at launch} (on by default) reconnects saved profiles and reopens local shells, splits and all,
|
||
in the folder they were in.
|
||
|
||
\section{Split panes}
|
||
|
||
Want two sessions side by side? Split the focused pane right with \keys{\mod+Shift+D} or down with
|
||
\keys{\mod+Shift+E} (also in the \menu{Session} menu, the right-click menu and the palette). The new pane asks
|
||
what to open: \ui{Local Machine} or any of your terminal profiles.
|
||
|
||
\shot{split.png}{A fresh split. Pick what goes in the new pane.}
|
||
|
||
Drag a divider to resize. Click \ui{×} on a pane's header to close it and its neighbour takes the space. Closing
|
||
the tab closes every pane in it.
|
||
|
||
\begin{quickwin}
|
||
Split right, open \code{htop} on one side and tail a log on the other. Now you look like a hacker in a film.
|
||
\end{quickwin}
|
||
|
||
% =========================================================================================
|
||
\chapter{Terminal superpowers}\label{ch:terminal}
|
||
\chapmeta{4 minutes}{You'll copy, search and scroll like you've used it for years}
|
||
|
||
\begin{tldr}
|
||
Select to copy, \keys{\mod+F} to search, Ctrl/\ph{E1C4}-click links. Right-click for the rest.
|
||
\end{tldr}
|
||
|
||
\section{Keyboard and mouse}
|
||
|
||
\renewcommand\arraystretch{1.45}
|
||
\begin{tabularx}{\linewidth}{@{}>{\leavevmode\heavy\color{ink}}p{24mm}X@{}}
|
||
\toprule
|
||
Copy & Select text, then \keys{\mod+C}. Nothing selected? \keys{Ctrl+C} interrupts the program as usual.\\
|
||
Paste & \keys{\mod+V}. Pastes are bracketed when the program asks for it, so editors won't auto-indent your paste
|
||
into a staircase. Pasting several lines into a shell asks first (turn that off in Settings).\\
|
||
Select & Drag for a range, double-click a word, triple-click a line, \kbd{Shift}-click to extend.\\
|
||
Links & Hold \kbd{Ctrl} (\kbd{\ph{E1C4}}) and click a URL to open it in your browser. Real hyperlinks that
|
||
programs print (\code{ls --hyperlink}, compilers) get a dotted underline; hover to see where they really go.\\
|
||
Scroll & Mouse wheel, or \keys{Shift+PageUp}, \keys{Shift+PageDown}, \keys{Shift+Home}, \keys{Shift+End}.\\
|
||
\bottomrule
|
||
\end{tabularx}
|
||
|
||
\begin{sidequest}[Why does the scroll wheel move the cursor in less?]
|
||
Full-screen programs (\code{less}, \code{vim}, \code{tmux}, \code{byobu}) use the terminal's ``alternate screen'', where the
|
||
wheel sends arrow keys instead of scrolling. Programs with mouse support (\code{htop}, \code{vim} with
|
||
\code{mouse=a}, \code{tmux} mouse mode) get your clicks directly. That's normal terminal behaviour, not a bug.
|
||
\end{sidequest}
|
||
|
||
\section{The right-click menu}
|
||
|
||
\ui{Copy}, \ui{Paste}, \ui{Select All}, \ui{Find}, \ui{Previous Prompt} / \ui{Next Prompt}, \ui{Copy Last Command
|
||
Output}, \ui{Send Snippet}, \ui{Port Forwards} (SSH), \ui{Split Right}, \ui{Split Down}, \ui{Export Output} (saves the
|
||
whole scrollback as a text file), \ui{Clear} and \ui{Reset}.
|
||
|
||
\section{Shell integration}
|
||
|
||
If your shell marks its prompts (fish 4, Starship and Powerlevel10k do already), Nexus Terminal knows where every
|
||
command starts and stops. \keys{\mod+Shift+Up} and \keys{\mod+Shift+Down} jump from prompt to prompt,
|
||
\ui{Copy Last Command Output} grabs just what the last command printed, and a thin bar beside each prompt shows how it
|
||
went: green for success, red for failure. Hover the bar for the exit code and how long it took.
|
||
|
||
\shot{shell-integration.png}{\code{make test} failed (red bar), \code{ls} worked (green bar).}
|
||
|
||
For bash, add this to \code{\textasciitilde/.bashrc} on the machine the shell runs on (the user manual has the zsh
|
||
version):
|
||
|
||
\begin{verbatim}
|
||
PS0='\[\e]133;C\a\]'
|
||
PROMPT_COMMAND='printf "\033]133;D;%s\007" "$?"; '"${PROMPT_COMMAND}"
|
||
PS1='\[\e]133;A\a\]'"$PS1"'\[\e]133;B\a\]'
|
||
\end{verbatim}
|
||
|
||
\section{Pictures in the terminal}
|
||
|
||
Programs that print images the iTerm2 way (\code{imgcat}, \code{wezterm imgcat}, \code{chafa -f iterm}) show PNG,
|
||
JPEG and GIF images right in the scrollback. They scroll with the text and never spill past the edge.
|
||
|
||
\shot{inline-image.png}{An image printed by a script, with the text carrying on underneath.}
|
||
|
||
\section{Find}
|
||
|
||
\keys{\mod+F} opens the find bar. Toggle \ui{Aa} for case-sensitive and \ui{.*} for regular expressions.
|
||
\kbd{Enter} for the next match, \keys{Shift+Enter} for the previous one, \kbd{Esc} to close. It shows
|
||
``3 of 17'' so you know where you are.
|
||
|
||
\section{When the connection drops}
|
||
|
||
The pane dims and shows a \ui{Disconnected} card with \ui{Reconnect} and \ui{Close}. If auto-reconnect is on,
|
||
it says \ui{Reconnecting…} with a \ui{Cancel} button, and a toast tells you which attempt it's on.
|
||
|
||
If the problem was a password or host key, you get a friendly dialog explaining what happened, with
|
||
\ui{Retry}, \ui{Edit Profile}, \ui{Known Hosts} (for host-key trouble) and \ui{Close}.
|
||
|
||
% =========================================================================================
|
||
\chapter{Never type it twice}\label{ch:repeat}
|
||
\chapmeta{6 minutes}{You'll stop retyping the same commands, and let Nexus Terminal watch the logs for you}
|
||
|
||
\begin{tldr}
|
||
\textbf{Snippets} store commands. \textbf{Broadcast} types into many sessions at once. \textbf{Triggers} watch output and
|
||
tap you on the shoulder.
|
||
\end{tldr}
|
||
|
||
\section{Snippets: \keys{\mod+Shift+S}}
|
||
|
||
Save commands you use a lot, with a name, description and folder. Search them, click
|
||
\ui{Send to Session}, and the command is typed into the active session followed by \kbd{Enter}.
|
||
|
||
\crop{snippets.png}{633}{384}{611}{402}{0.8\linewidth}{The snippet library, organised into folders.}
|
||
|
||
Snippets can have blanks to fill in:
|
||
|
||
\begin{itemize}
|
||
\item \code{\{\{hostname\}\}}, \code{\{\{date\}\}}, \code{\{\{time\}\}} and \code{\{\{timestamp\}\}} are filled in for you.
|
||
\item Anything else, like \code{\{\{service\}\}}, is asked for when you send it.
|
||
\end{itemize}
|
||
|
||
So \code{journalctl -fu \{\{service\}\}} asks ``service?'' and tails whichever one you type.
|
||
|
||
\section{Broadcast: \keys{\mod+Shift+B}}
|
||
|
||
Turn broadcast on and everything you type goes to \emph{every} connected terminal. The status bar shows
|
||
\ui{BROADCAST} so you can't forget it's on.
|
||
|
||
\shot{broadcast.png}{Broadcast is on: the status bar says so in no uncertain terms.}
|
||
|
||
To broadcast to only some sessions, right-click the \iBroadcast{} button (or \menu{Session\then Broadcast
|
||
targets…}), tick the ones you want and click \ui{Apply \& Enable}.
|
||
|
||
\begin{danger}[With great power…]
|
||
Broadcast doesn't care which tab you \emph{meant}. Double-check the target list before you type anything
|
||
destructive. \code{sudo reboot} into twenty servers is very efficient and very memorable.
|
||
\end{danger}
|
||
|
||
\section{Triggers: let it watch for you}
|
||
|
||
\menu{Session\then Trigger Rules} (or the palette). Each rule has a pattern (plain text or a regular
|
||
expression), a case-sensitivity switch, an on/off switch, and an action:
|
||
|
||
\begin{center}\small
|
||
\begin{tabular}{@{}ll@{}}
|
||
\ui{Notify} & shows a toast\\
|
||
\ui{Highlight tab} & briefly outlines the pane\\
|
||
\ui{Notify + Highlight} & both\\
|
||
\ui{Sound} & asks your OS for attention (a bouncing dock icon or flashing taskbar button) and shows a toast\\
|
||
\end{tabular}
|
||
\end{center}
|
||
|
||
\crop{triggers.png}{725}{610}{725}{625}{0.75\linewidth}{Three rules: shout about errors, ping when a build finishes, and one switched off for now.}
|
||
|
||
Rules check each complete line of output, with colours stripped out first.
|
||
|
||
\begin{quickwin}
|
||
Add a rule for \code{BUILD SUCCESSFUL} with the \ui{Sound} action, start a long build, and go and make a cup of tea.
|
||
Nexus Terminal will tell you when it's done. (Or \code{(?i)error|fatal} for the opposite.)
|
||
\end{quickwin}
|
||
|
||
% =========================================================================================
|
||
\chapter{Files: SFTP and drag-and-drop}\label{ch:files}
|
||
\chapmeta{4 minutes}{You'll move files to and from servers without leaving the terminal}
|
||
|
||
\begin{tldr}
|
||
Click the \iFolder{} on an SSH tab. Or drop a file onto the terminal and choose \ui{Upload}.
|
||
\end{tldr}
|
||
|
||
\section{The SFTP browser}
|
||
|
||
Click the \iFolder{} folder icon on an SSH tab, \menu{Session\then SFTP browser}, or type ``sftp'' in the palette.
|
||
It opens in the side dock next to your terminal, in the folder your shell is in if the shell reports it
|
||
(fish does; bash and zsh need a one-line hook, see the user manual).
|
||
|
||
\shot{sftp.png}{Browsing the server's files next to the terminal.}
|
||
|
||
\begin{itemize}
|
||
\item Move around with the breadcrumb trail, the \code{..} entry or \ui{Go to path}.
|
||
\item Upload files; download one or many to a folder you choose.
|
||
\item Rename, delete (it asks first), make folders, refresh.
|
||
\item \iStar{} bookmarks the current folder, per profile.
|
||
\item Ctrl-click (\ph{E1C4}-click) or Shift-click to select several things. Transfers show progress as they go.
|
||
\end{itemize}
|
||
|
||
\section{Drag and drop}
|
||
|
||
Drop files onto a terminal and choose:
|
||
|
||
\begin{description}
|
||
\item[Upload to current directory] Pick the remote folder (SSH only).
|
||
\item[Paste contents] Types the file's contents into the terminal, as if you'd typed it.
|
||
\end{description}
|
||
|
||
The upload picker looks like the SFTP browser but shows folders only, labelled \proto[amber]{READ ONLY} if you can't
|
||
write there and \proto[rose]{NO READ} if you can't look inside. Keyboard fans: \kbd{↑}\kbd{↓} to move, \kbd{Enter} to
|
||
choose, \kbd{Backspace} to go up, \kbd{Esc} to cancel. If the SFTP browser is open, the picker starts in the same folder.
|
||
|
||
% =========================================================================================
|
||
\chapter{Port forwards}\label{ch:forwards}
|
||
\chapmeta{3 minutes}{You'll reach a database or web app that only listens on the server}
|
||
|
||
\begin{tldr}
|
||
\emph{Local} forwards bring a remote port to your machine. \emph{Remote} forwards do the opposite.
|
||
\end{tldr}
|
||
|
||
Forwards saved in an SSH profile (under \ui{Port Forwarding}, with \ui{Active} ticked) start when you connect.
|
||
To manage them on a live session, right-click the terminal\then\ui{Port Forwards}, or \menu{Session\then Port forwards}.
|
||
|
||
\begin{description}
|
||
\item[Local \iArrow] Listen on your computer, forward to somewhere the server can reach.
|
||
Example: \code{127.0.0.1:15432}\then\code{127.0.0.1:5432} lets your desktop database app talk to Postgres on
|
||
the server as if it were local.
|
||
\item[Remote \ph{E058}] Ask the server to listen and send connections back to somewhere \emph{your} computer can reach.
|
||
Great for showing a colleague the dev server running on your laptop.
|
||
\end{description}
|
||
|
||
Active forwards are listed with an \proto[accent]{L} or \proto[violet]{R} badge and a stop button. Toasts tell you when one
|
||
starts, stops or fails.
|
||
|
||
% =========================================================================================
|
||
\chapter{Recordings}\label{ch:recordings}
|
||
\chapmeta{2 minutes}{You'll have a replayable record of exactly what happened}
|
||
|
||
\keys{\mod+Shift+R} starts and stops recording the active session. A red dot appears on the tab and \ui{REC} in
|
||
the status bar. Recordings are standard asciicast v2 files, so other tools (like \code{asciinema}) can play them too.
|
||
|
||
\crop{recordings.png}{712}{392}{690}{415}{0.75\linewidth}{The recordings browser. Play, delete, or tidy up in bulk.}
|
||
|
||
The browser (sidebar footer, \menu{Session} menu or palette) shows how many recordings you have and how much space
|
||
they take. Play or delete each one, or use \ui{Clean up} to remove recordings older than 7, 30 or 90 days, or to keep
|
||
the total under 1\,GB or 5\,GB. Playback has play/pause, restart, a seek bar and speed control.
|
||
|
||
\begin{protip}
|
||
Record the next time you do something fiddly and rare (a database failover, a certificate rotation). Six months
|
||
later, ``how did we do that again?'' has an answer you can literally watch.
|
||
\end{protip}
|