Quick answer: How do I use the terminal in Workbench?
Workbench lets you open a terminal on your Mac from another Mac, iPad, or iPhone.
To get started, turn on Enable Remote Access and Allow Terminal Access in Workbench settings on the Mac you want to connect to.
Your sessions keep running after you close the window or disconnect, so you can pick up where you left off from any device.
You don’t need to install tmux or anything else. Workbench includes everything it needs.
Terms used in this article
Host Mac: the Mac whose terminal you’re using. Commands always run here, using this Mac’s files and tools.
Your device: the Mac, iPad, or iPhone you’re typing on.
Set up the host Mac
Before you get started, you'll need Workbench installed and up to date on the host Mac and on your device.
On the host Mac:
Open Workbench and set up remote access.
Go to Settings → Remote Access and turn on Enable Remote Access.
Go to Settings → Terminal and turn on Allow Terminal Access.
Keep the host Mac awake and online while you work. To keep the Mac awake but let its display sleep, turn on Settings → Remote Access → Prevent System Sleep.
How to open a terminal
Connect to another Mac
In Workbench’s computer list, find the host Mac.
Choose Terminal. If you also want to see the screen, choose Both.
Workbench opens your existing session if there is one. If not, it creates a new one.
On Mac: the terminal opens in its own window.
On iPad and iPhone: use the Screen and Terminal controls to switch between screen sharing and the terminal.
You don’t need to view the screen to use the terminal.
Open a terminal on the Mac you’re using
In the Mac app, choose File → Open Terminal, or click Local Terminal in the computer list.
Sessions you start here are also available when you connect to this Mac from another device.
Create and switch terminal sessions
Each tab is its own session, with its own shell, folder, and running programs.
Device | New session | Switch sessions |
Mac | Click + in the terminal window, or press ⌘T | Click a tab |
iPad | Tap the ⌄ arrow next to Terminal and choose New Remote Terminal | Tap a tab |
iPhone | Tap the ⌄ arrow next to Terminal and choose New Remote Terminal | Tap the same arrow and choose a session |
A new session starts in the same folder as the session you have selected. If that folder isn’t available, it starts in your home folder.
Tab names update on their own to show the program or folder in use.
Rename a tab (Mac and iPad): open the tab’s … menu and choose Rename…. Clear the name to go back to automatic names.
The dot next to a tab name (Mac and iPad): a gray dot means no window is showing that session right now. The session is still running.
Leave work running and come back later
Sessions stay running on the host Mac. You can start a task on your iPad, disconnect, and pick it up later from your iPhone or Mac. Just reconnect to the same host Mac and choose the session.
If you... | What happens |
Switch tabs or go to the screen view | The session keeps running |
Close the terminal window or disconnect | The session keeps running on the host Mac |
Quit Workbench on the host Mac | The session stays on the host Mac, but you can’t reach it remotely until Workbench is running again |
Choose End Terminal, or click a tab’s × and confirm | The session ends and its programs stop |
Restart or shut down the host Mac | All sessions end |
If the host Mac goes to sleep, your commands pause. Keep it awake for tasks that need to keep running.
💡 Close vs. end: closing the window or disconnecting leaves your work running. Ending a tab stops it.
End a terminal session
On Mac or iPad: click the tab’s ×, or open its menu and choose End Terminal. Workbench asks you to confirm, since this stops any programs running in that session.
On iPhone: quit the program you’re using, then type
exitat the prompt. You can also end sessions from Workbench on a Mac or iPad.
Use the terminal on iPad and iPhone
Type and use special keys
Type with a hardware keyboard or the onscreen keyboard. Tap the keyboard button in the toolbar to show or hide the onscreen keyboard.
The row above the keyboard has Esc, Ctrl, Alt, ⌘, Tab, arrow keys, and two shortcuts:
^C sends Control-C, which usually stops the current command.
^D sends Control-D, which usually signals end of input. At an empty prompt, it can close the shell.
Tap a modifier like Ctrl to apply it to the next key. Double-tap it to keep it on, then tap again to turn it off.
Scroll and resize text
Swipe to scroll. Pinch to make text bigger or smaller in the current view.
To set your default font and size, go to Settings → Terminal.
Copy text
Press and hold the text you want.
In the Select Text screen, adjust your selection and tap Copy. If nothing is selected, tap Copy All to copy everything on screen.
Tap Done to go back without copying.
To copy older output, scroll it onto the screen first.
Dictate
Tap the microphone and speak. Tap it again to stop. Workbench adds the text to the terminal but doesn’t press Return, so you can check it before you run it.
Copy, paste, and add files on Mac
Use ⌘C to copy and ⌘V to paste.
You can also drag files into the terminal, or copy a file or image and paste it in.
Add files to a remote terminal
Workbench uploads the files to the host Mac and types their paths into the terminal, without pressing Return. You can use the paths in a command or paste them into any program that accepts file paths.
Progress: the upload panel shows progress and lets you cancel.
Switching tabs: paths go into the tab where you started the upload. If you switch tabs, go back to that tab when the upload finishes.
Where files go: uploaded files are saved to a temporary folder on the host Mac, not your project folder. Move any files you want to keep.
Folders: you can’t upload folders. Compress the folder into a .zip first.
Size limit: On some connections, uploads in progress share a limit of about 5 MB. If you see “Too large for this connection,” try fewer or smaller files. Direct connections have no limit.
Add files to a terminal on the Mac you’re using
Workbench types the file’s existing path. Pasted images, and files from some other apps, may be saved to a temporary file first.
Open a session in Apple’s Terminal app
In a local terminal window on your Mac, open a tab’s … menu and choose Open in Terminal.app.
The same session opens in Apple’s Terminal app, with the same shell and running programs. You can return to it in Workbench anytime.
This only works for sessions on the Mac you’re using.
Change how the terminal looks
Go to Settings → Terminal to change:
Font: any monospaced font on your device, or Default
Font size: 8 to 32 points
Appearance: Light, Dark, or Auto (matches your device)
Changes apply right away. Settings are per device, so set them on each device you use.
Troubleshooting
“Terminal access is turned off on the remote computer”
On the host Mac, go to Settings → Terminal and turn on Allow Terminal Access.
“Update Workbench on the remote computer to use the terminal”
The host Mac has an older version of Workbench. Update it, then reconnect.
“Remote terminal is not ready”
Check that the host Mac is awake, Workbench is running on it, and your connection has finished. Reconnect if needed.
An error says to install tmux (brew install tmux)
You don’t need to install tmux. Workbench includes it. Update Workbench on the host Mac to the latest version and try again.
My session is missing
Make sure you’re connected to the same host Mac. A session can’t be brought back if it was ended, its shell was closed, or the host Mac restarted.
My Terminal.app or iTerm session isn’t showing up
Workbench only lists sessions started in Workbench. It doesn’t pick up sessions already running in other terminal apps.
A file upload failed
Check the upload panel for the reason. Common causes: you tried to upload a folder, the file can’t be read, or the file is over the size limit for your connection. If you lost your connection, reconnect and upload again.