Command Line Interface

The Gitpod CLI is one of the three main ways to interact with Gitpod, besides from within an editor or from the dashboard. It provides ways to interface with and manage environments, interact with Automations and execute some basic operations against runners and organizations.

Installing the CLI

Installing the Gitpod CLI is as easy as downloading and executing a single binary file. You can download one of the platform-dependent releases (listed below) or run this one-liner if you’re running a UNIX system.

This script will install the CLI to $HOME/.local/bin, which should already be in your $PATH. After installing the CLI, you should be able to run gitpod from anywhere.

Alternatively, you can download the CLI using the following links:

• darwin-amd64
• darwin-arm64
• linux-amd64
• linux-arm64
• linux-amd64
• windows-amd64
• windows-arm64

Getting started with the CLI

You need to log in to interact with resources under your Gitpod account. Logging in is done using the login command, which gives you a link and opens it automatically in the default browser, prompting you to authorize the CLI integration.

Once login is successful, try to list all environments:

Machine-readable output support

There are times, such as when using the output of the CLI with other tools, where a machine-readable output format is desirable. The currently supported alternate formats are JSON and YAML, which can be specified with the --format flag (or -o for short).

Within environments

Every Gitpod environment comes with the CLI preinstalled (you can find it under gitpod). The CLI is by default authenticated with the current environment and, therefore, can access basic context-based actions, such as gitpod environment stop, gitpod environment logs, or gitpod devcontainer rebuild.

Upgrading the default context

You’ll want to create a new, fully authenticated context to access resources like your user account or even other environments. To do so, execute the following inside the environment:

After logging in, the new context will automatically activate, and you’ll be able to use the full extent of the CLI feature set.

SSH

Accessing environments (running both locally and remotely) is done through the Secure Shell protocol. For instance, our VS Code Desktop integration handles SSH connections automatically. Still, if you’d like to connect to an environment with a custom editor or your terminal, you’ll need to download and set up the Gitpod CLI.

With the Gitpod CLI, you can SSH into any running environment like so:

This will wrap an SSH session authenticated with a Gitpod SSH key (which we, by default, generate under ~/.ssh/gitpod/id_ed25519).

Executing SSH commands directly

If you want to execute just one sequence of commands rather than starting a whole interactive SSH session, you can provide additional arguments after a -- at the end of the command.

Caveats

CLI has limited access when running from within an environment

When utilizing the CLI built into each environment, Gitpod logs you in automatically. This access, though, is limited to the context of the current environment, and further authentication is necessary. See Upgrading environment context for more info.