Quick Start

Welcome to Prompt!

After downloading Prompt, you can use it immediately. You type commands into the input box at the bottom of the screen like normal, and when you hit [return] the command will be executed. You’ll notice that each command is run in its own block. The block will groups the command with its output in the terminal screen. The block will expand to fill the screen as more output is received.

The blocks give information about the command and its status. The box with the number in it shows you the “line number” of the command within the screen. The color of the box that contains the line number shows you the command status, light blue means running, and light gray means the command has terminated.

When a command is running, you can interact with it like normal when the command has focus. When commands are initially run they get focus by default, and when they terminate they give focus back to the input box. You can easily shift focus between your commands or the input box using the mouse or “Cmd-I” to focus the input box, and “Cmd-L” to focus a command line. Note that Cmd-I will work in any context to focus the input box. To shift the focus between commands you can use the mouse or “Cmd-UpArrow” / “Cmd-DownArrow” (or Cmd-PageUp/Cmd-PageDown) will move the focus between commands.

So far we’ve been working in one screen (tab). You can easily create a new screen (tab) by clicking the “+” in the tab bar (right above the input box), or by pressing “Cmd-T”. Switching between tabs can be done with the mouse or by using “Cmd-[digit]” to switch to the nth tab. Cmd-LeftArrow and Cmd-RightArrow will also work to change tabs.

Prompt also has the concept of sessions. A session is just a set of screens (tabs). You can see your sessions listed in the left column of the UI. You start with 1 session named “default”. You can easily create a new session by clicking on “new session” in the left bar or by using a “meta-command” (we’ll discuss those later). Each session is independent from the others. You can use sessions to set up custom sets of tabs for different projects, common configurations, or different remote machines. In the future, Prompt will support sharing sessions with your team or having a joint shared session that everyone can view and contribute to.

Sessions and screens are persistent. The history and state of each tab is preserved across reboots, network disconnections, remote machine reboots, and time. Any command you’ve ever run in Prompt will be remembered (unless of course you choose to delete it).

So far we’ve seen how to use key-bindings (like Cmd-T) or the mouse to interact with our terminal. But Prompt also supports meta-commands that can manipulate every aspect of the terminal. In fact, the UI itself interacts with prompt using these same meta-commands making Prompt extremely customizable and scriptable. For instance, “Cmd-T” is actually bound to the meta-command /screen:open. Here are some examples of meta-commands:

# create a new tab
/screen:open 

# create a new session
/session:open

# archive the current tab (hides, but does not remove history)
/screen:archive

# removes the tab and also purges all output and history
/screen:purge

# archive the current session (not visible)
/session:archive

# deletes the session, purges all ourput and history
/session:delete

# change the current session
/session 1        # switches to the first session
/session default  # switches to the session named "default"

/screen 5         # switches to the 5th tab
/screen +1        # switches to the next tab
/screen E         # switches to the last tab
/screen S

/screen:set tabcolor=red    # sets the tab color
/screen:set name="webpack"  # sets the tab name

/session:set name="prompt dev"  # sets the session name

In fact, everything can be controlled by these meta-commands. If you can do something in the UI, you can do it with a meta-command. Even switching down to switching the input focus or generating command completions. During the beta the meta-commands will be evolving, here is current meta-command reference.

So far we’ve been running commands on our local computer. Prompt of course supports regular ssh (as a block) that you can run to log into remote machines but regular ssh connections suffer from two problems – (1) you can get disconnected, and (2) no universal history. To get the most out of Prompt you need to set up a “remote”. This functions as a virtual SSH connection that can recover from disconnects, save your environment (working directory, environment variables, functions, etc.), and save its history.

Prompt was designed with security in mind. All authentication to remote machines is done using standard SSH (Prompt does not implement any special authentication scheme of its own). All communication with a remote is done via stdout and stdin, so the helper that runs on the remote machine will never open any ports, or need any additional privledges.

To do that you need to create a new connection for the machine that you are logging into. Click “Add Connection” in the bottom-left of the screen and you’ll see a small form. Prompt uses regular SSH to make its connections. Use the “authmode” dropdown to add an ssh key (equivalent to “-i”) and/or a password (note that ssh keys are more secure than passwords, and we recommend that you always use keys to log into your servers and not password authentication). If your connection is not standard, and requires some other type of authentication or a changing password (OTP), you’ll have to select “connectmode” as “manual”.

To allow for persistent connections, Prompt will install a helper on the remote machine (mshell). This helper only communicates via stdin and stdout to Prompt. It does not open any ports or network connections, does not need any additional permissions, and will only write to the disk if you are running detached commands (special types of commands that can stay running even when Prompt is disconnected). The helper program will be open-source. To re-install the helper run the meta-command /remote:install.

Now that we’ve set up our first remote we can use it. In any screen you can use the cr command. cr will change your remote (like cd can change directories). You just type cr [remotename-or-alias] and you’ll see your prompt change to reflect that you’re now running commands against the selected remote. Note that a screen can have a mix of commands from local or from a remote (you can see the remote that ran the command to the right of the line number).

Every session and tab can now switch to the newly added remote using cr. Every tab keeps its own remote state, so you might have different current working directories in each tab (just like a local connection).

Let’s say I have a remote named “server01”. If I cr server01 I get a complete virtual environment working on server01. cd or exporting an environment variable are all sticky to that tab. I can create an additional virtual environment by using a colon: cr server01:2 will change to the server01 remote to a named session “2”. Any number of virtual environments can be made in a tab for each remote and all will be independent.

In the future Prompt will allow you to share these virtual environments between tabs and copy/clone their settings between them.

To reset a remote back to its initial login state, use the meta-command /reset (useful if you’ve recently updated your .bashrc or .bash_profile.

Note: You can change the color of a remote’s prompt with the meta-command: /remote:set color=red.

To access standard command history, you can press UpArrow just like in your normal terminal. These commands are filtered to be from the current screen and the current remote.

But Prompt keeps command history across all remotes, all tabs, and all sessions so you can easily recall a command you may have run in a separate tab or on a different machine to run. You enter history search using “Ctrl-R” or “Cmd-H”. From there you can still hit up or down arrow to navigate your history, but there are additional filters. You can toggle search to include all remotes, everything in your current session, or your global history.

Prompt keeps metadata for all commands that you run through it, including current working directory, status code, command duration, time, remote, etc. In the future you will have access to an advanced search where you can find commands using any of the tracked metadata fields. In team mode you’ll also be able to search through the commands your teammates have shared with you as well.

Prompt sends only very basic telemetry once every 8-hours that includes: number of commands run, minutes of activity, and client version number and architecture along with a random client UUID to aggregate the data together. To disable all telemetry, you can run the meta-command: /telemetry:off.

(Note that telemetry was added in v0.1.1, so if you’re using v0.1.0 no telemetry data is sent at all and the /telemetry command will throw an error)

Prompt is still in private beta and is evolving very fast. If you have questions, bugs to report, or feature requests please join the Prompt Discord Channel to get immediate help. You can also email me: mike (at) getprompt.dev.