Warp Terminal

Overview

Warp is "the terminal for the 21st century".

Warp Logo

Currently Warp only runs in macOS, but there are plans to support web (through WASM), Linux, and Windows in the future.

Warp functions more like a standard text editor than most terminal programs. The cursor can be positioned by using the arrow keys or clicking anywhere in a command. Any text can be selected, copied, and pasted.

Warp currently only supports the shells Zsh, Bash, and Fish, and it does so without any configuration. If your default shell is not one of these, Warp will default to Zsh. The Warp team has stated that they would like to support Nushell in the future.

Warp is implemented in Rust which makes it very fast. From the Warp FAQ, "The UI is built on our own rendering layer that leverages lower-level graphics APIs like Metal."

Warp uses GPU-acceleration. From the Warp FAQ, "Picking GPU acceleration has allowed us to be a way over 60fps on a 4K screen."

Vim keybindings are not currently supported, but the Warp team has stated that they want to add support. See issue 159.

Installing

To install Warp using Homebrew, enter brew install warp. This creates Warp.app in your Applications directory.

Running

Double-click Warp.app in your Applications directory to launch it. The first launch will prompt you to sign up.

When an update is available an "Update Available" button will appear on the right side of the title bar. Clicking displays a popup with an "Install update" option that lists the new version number. Click it download the new version.

When quitting Warp if there are any processes running inside it, a dialog will appear allowing you to verify that you really want to quit which will kill the processes. Click the "Show running processes" button to see a list of the processes.

Help

To get help on using Warp, open the "Warp Essentials" panel by clicking the button on the right side of the title bar. This contains four sections titled "What's New?", "Getting Started", "Maximize Warp", and "Advanced Setup".

Warp Essentials panel

To view "Keyboard Shortcuts", click the keyboard icon.

To open the Settings dialog, click the gear icon.

For online help, click "Docs" at the bottom of the "Warp Essentials" panel or browse Warp Documentation.

Hierarchy

Warp uses the terms window, tab, pane, and block. These have the following relationships:

Windows

Each window can contain any number of tabs.

To open a new window, select File ... New Window or press cmd-n.

To move a window to a different monitor, select one of the "Move to" options on the Window menu.

To switch to full-screen mode, select "Enter Full Screen" from the Window menu or press fn-f. To exit full-screen mode, hover over the top of the window and click the green circle or press fn-f again.

Tabs

Each tab can contain any number of panes.

To open a new tab, click the "+" to the right of the last open tab or press cmd-t.

To rename a tab, right-click it, select "Rename", enter the new name, and press the return key.

To change the color of the bottom border and background gradient of a tab, right-click it, and select one of the six theme colors at the bottom of the popup.

To navigate to the tab to the right, press cmd-}.

To navigate to the tab to the left, press cmd-{.

To reorder tabs, drag them left or right.

Dragging a directory from the Finder onto the Warp app dock icon opens a new tab in that directory where the title is the directory path.

Panes

Each pane can hold any number of blocks.

To create a new pane, right-click and select one of the "Split pane" options to open a new pane on the right, left, down (bottom), or up (top).

I defined the following keyboard shortcuts of the form opt-shift-{arrow-key} to simplify creating new panes:

To close the currently focused pane, enter "exit" or press cmd-w. To close any pane, right-click in it and select "Close pane". Closing the last pane in a tab closes the tab. Closing the last tab in a window closes the window.

To navigate to the next pane, press cmd-].

To navigate to the previous pane, press cmd-[.

To navigate to a pane in a specific direction, press cmd-option-{arrow-key}.

To resize panes, drag a divider line or press cmd-ctrl-{arrow-key}.

To temporarily change the current pane to occupy the entire window, open the command palette and select "Toggle Maximize Active Pane" or press cmd-shift-return. To undo this, execute the same command again.

To see a list of all current panes across all tabs, press cmd-shift-p. This opens a dialog that lists the panes. Alternatively, press cmd-p to open the command palette and type "@". Each pane is described by providing its current working directory and the last command executed in it. To navigate to one of the panes, click its description.

Currently there is no way to swap the positions of two panes within their tab.

Blocks

Entering a shell command creates a new "block".

Blocks are divided by thin horizontal lines. By default there is some vertical space on both sizes of the lines. To remove this space, open Settings, select Appearance, and toggle the "Compact mode" option to be on.

There are two ways to select a previous block:

  1. Scroll up until it is visible and click it.
  2. Click any block and use the up and down arrow keys to navigate to it.

There are many Warp commands that operate on a block. To execute such a command, open the block command menu by doing one of the following:

Block commands include:

To scroll to the top of the output in a block, click its command at the top of the block.

To clear all the blocks in the current pane, open the command palette and select "Clear Blocks", enter the Warp command "clear block", or press cmd-k.

Commands

When entering a shell command or Warp command:

For recognized commands, a suggested completion may appear in dimmed text. To accept the suggestion, press the right arrow key.

To execute the entered command, press the return key.

Dragging a file or directory from the Finder to the command entry area inserts its full path.

To enter multiple commands on separate lines, press ctrl-j (runs the "Insert Newline" command) after each command except the last. Pressing the return key executes all of the commands and displays the output of each command.

To see a brief description of a command, subcommand, or flag in a popup provided by the "Command Inspector", hover over it.

To recall a command previously entered in the current pane, repeatedly press the up arrow key until the desired command is highlighted. Press the return key to execute it.

To search command history, workflows, and AI commands, press ctrl-r. To limit the search to one of these three categories, click the "history", "workflows", or "AI command search" button. Then enter text to perform a fuzzy search. For example, entering "start" will find any command containing those letters in that order, but not necessarily together. This would match "fastlane screenshots".

A block cannot be re-executed. However, you can:

Command Editing

There are many keyboard shortcuts that trigger text editing commands. The following table summarizes the most useful shortcuts.

CommandKeyboard Shortcut
Clear Command Editorctrl-c
Clear Screenctrl-l
Insert Newlinectrl-j
Move Backward One Wordoption-left-arrow
Move Forward One Wordoption-right-arrow
Move to Start of Linecmd-left-arrow
Move to End of Linecmd-right-arrow
Select Allcmd-a
Delete All Leftcmd-delete
Delete All Rightcmd-fn-delete
Delete Word Leftoption-delete
Delete Word Rightoption-fn-delete

For more keyboard shortcuts, see the Keyboard Shortcuts.

AI Commands

To generate a shell command using an AI search, enter a # character of press ctrl-`.

Warp AI Command Search

Enter English text describing the desired command and press the return key. For example, entering "delete local git branch" suggests "git branch -d branch_name". To accept this suggestion, click the "Input Command" button or press cmd-return. Replace any placeholders (such as branch_name above) and press the return key to execute the command.

Sometimes the suggested commands are correct for Linux and not macOS. To get macOS equivalents, add "on mac" to the English description.

AI search can also be used to ask questions not related to shell commands. For example, asking "What is a Whippet?" gives the suggestion "A whippet is a small breed of dog with a distinctively tightly curled tail." Unfortunately this is a bad description.

Workflows

Workflows are named sets of shell commands (typically just one) that are parameterized. They are similar to snippets in code editors.

Each workflow is defined by a .yaml file.

To search for a workflow, press ctrl-shift-r.

Warp Workflows

In the popup that appears, select a category in the left nav such as "git". Then click one of the workflows to copy it to the current block. Replace any placeholders and press the return key to execute the workflow.

Warp ships with over 100 predefined workflows.

To install additional workflows, see the GitHub repository warpdotdev/workflows.

To create custom workflows, see Creating Custom Workflows.

Selecting Text

To select text, perhaps to copy it, drag over it as you would in most editors. Additionally "Smart-Select" allows you to to select a file path, URL, email address, IP address, or floating point number by double-clicking it. To enable or disable this feature, see Settings ... Features ... Terminal ... Double-click smart selection.

Finding Text

The "Find" and "Find Within Block" commands open a dialog in the upper-right corner of the pane from which they were issued. Search text can be entered here.

Warp find dialog

All matches are highlighted in yellow except for the currently selected match is highlighted in orange.

The total number of matches found and the number of the currently highlighted match are displayed. For example, "2/5" indicates that there a five matches and the second match is the one highlighted in orange.

In addition, the following buttons are provided:

Block Bookmarks

Blocks can be bookmarked to make it easy to find them in the future.

To toggle whether a block is bookmarked, click its bookmark icon in the upper-right. Alternatively if the block is selected, press cmd-b.

Warp Bookmark

The pane scrollbar on the right will contain horizontal lines that indicate the location of each bookmarked block in the pane.

The color of the bookmark icon and the horizontal lines is based on the selected theme.

Hovering over one of the horizontal lines displays a popup that contains the working directory of the block, the command that was run, the first two lines of its output, and the number of lines that were omitted.

To navigate to a bookmarked block, click one of these lines.

To navigate to the previous bookmarked block, press option-up-arrow.

To navigate to the new bookmarked block, press option-down-arrow.

Block bookmarks are not saved across sessions. This may be a bug.

Command Palette

To quickly find and execute a Warp command (not a shell command), open the command palette by pressing cmd-p, filter the list of commands by typing part of its name, and click a command.

Warp Command Palette

Themes

Warp supports themes that change the look of the user interface. Each theme can define colors, gradients, and a background image and is defined by a .yaml file.

To choose a theme, open the command palette and select "Open Theme Picker" or press cmd-ctrl-t. This opens a panel on the left that lists all the available themes.

Warp Theme Picker

The list of themes can be filtered by entering part of a theme name.

The themes listed appear to be in a somewhat random order. Currently there is no option to sort them by name or separate them into groups of light and dark themes.

Selecting a theme changes the display to preview the theme.

To change the theme being used to the selected one, click the checkmark at the bottom. To close the theme picker without changing the theme being used, click the X at the bottom.

Custom Themes

The files that define custom themes must be placed in the ~/.warp/themes directory. Create this directory if it doesn't exist.

To download additional open source themes, see the Git repository warpdotdev/themes. This contains several subdirectories such as base16, holiday, standard, and warp_bundled (themes that ship with Warp). Each subdirectory contains a README.md file that displays previews of each theme defined in the directory.

To use a theme, download its .yaml file and corresponding background .jpg file, if it has one. For example, to use the "thanksgiving" theme defined in the holiday directory, create a holiday directory in the ~/.warp/themes directory and download the files thanksgiving.yaml and thanksgiving_bg.jpg into it. Then open the Theme Picker and select the "Thanksgiving" theme.

To create a custom theme, create a .yaml file similar to the one shown below. Including a background image is optional. Each theme defines accent, background, and foreground colors. The details property indicates whether it is lighter or darker theme.

A theme defines two sets of ANSI escape "terminal" colors, one for "bright" and one for "normal". Each set defines the colors to be used in place of black, blue, cyan, green, magenta, red, white, and yellow. The selected colors can differ from these color names. For example, a theme might choose to use a shade of orange for yellow.

ANSI colors use numbers 0 to 15. Normal colors are 0 to 7 and bright colors are 8 to 15.

background_image:
  path: holiday/thanksgiving_bg.jpg
  opacity: 47 # 0 to 100
accent: '#b3deef'
background: '#282828'
details: darker # for dark theme?
foreground: '#eeeeee'
terminal_colors:
  normal:
    black: '#282828' # 0
    red: '#f43753' # 1
    green: '#c9d05c' # 2
    yellow: '#ffc24b' # 3
    blue: '#b3deef' # 4
    magenta: '#d3b987' # 5
    cyan: '#73cef4' # 6
    white: '#eeeeee' # 7
  bright:
    black: '#1d1d1d' # 8
    red: '#dc9656' # 9
    green: '#383838' # 10
    yellow: '#484848' # 11
    blue: '#b8b8b8' # 12
    magenta: '#e8e8e8' # 13
    cyan: '#a16946' # 14
    white: '#ffffff' # 15

For more detail see Custom Themes.

Creating a permalink for a block provides a URL that can be shared with others to view the shell command and output associated with the block.

There are multiple ways to initiate create a permalink:

Either way a dialog will appear.

Warp Share Block

Click the "Create and Copy Link" button to create the permalink. This displays the permalink URL and copies it to the clipboard.

Permalinks remain active until they are deleted. To see all the permalinks that have been created, open the Settings dialog by pressing cmd-,. Then select "Shared blocks" in the left nav. To delete a permalink, click its vertical ellipsis and select "Unshare". Confirm this by clicking the "Unshare" button in the dialog that appears.

Settings

There are several ways to view and modify settings:

Warp Settings

The left nav of the Settings dialog contains the following sections:

Keyboard Shortcuts

To view all the keyboard shortcuts, open the "Warp Essentials" panel by clicking the button on the right side of the title bar and click the keyboard icon.

To modify keyboard shortcuts, see "Keyboard shortcuts section" described in "Settings" above.

Warp Settings Keyboard Shortcuts

Issues

I have filed the following issues: