←  back to changelog

December 18, 2023

Take Gitpod to your local command line

Workspaces that include all the tools developers need to start work and become ready-to-code are even more accessible and flexible, with the new Gitpod CLI for personal workspace management.

For developers you can now start and manage workspaces directly from your terminal, composing with your other favorite command-line utilities, and writing custom scripts.

For platform engineers you can now incorporate the CLI into your own internal developer platform to bring ready-to-code workspaces to your developers through deeper integrations.

Please note: The Gitpod CLI is an additional CLI to the existing CLI (gp) that is available in all Gitpod workspaces. In future these two experiences will be aligned.

Getting Started

To get started, install the CLI with the following command:

language icon bash
brew install gitpod-io/tap/gitpod

Everything installed? Let’s login and start using the CLI to create and manage workspaces.

Login to your Gitpod host

Using browser-based or token-based authentication:

  1. gitpod login to login to Gitpod.
  2. gitpod login --host="yourcompany.gitpod.cloud" for Gitpod Enterprise.
  3. gitpod login --token <access-token> to authenticate with an Access Token.

Note: Access tokens are generated from your User Settings in the Gitpod dashboard.

Tip: Use gitpod whoami to see your authenticated organization, host, etc.

Create and open a workspace in your editor

language icon bash
gitpod workspace create https://github.com/gitpod-io/empty --open

Or, create and open a workspace with SSH

language icon bash
gitpod workspace create https://github.com/gitpod-io/empty --ssh

Tip: Use --editor to override your default editor selection. Use gitpod workspace list-editors to see a list of possible editor options.

Managing workspaces

There’s a lot more you can do with the Gitpod CLI including listing and deleting workspaces. We suggest you explore the CLI using the help pages. Start by typing gitpod to start exploring.

See Gitpod CLI for more.

Frequently Asked Questions

Can the CLI be used in automation? Yes. You can install and use the Gitpod CLI in CI pipelines, bash scripts or other automation by logging in via access token based authentication.

Does this mean Gitpod now has two CLIs? Gitpod will continue to support the gp CLI within Gitpod workspaces alongside this new Gitpod CLI. The gp CLI will now be referred to as the “workspace CLI”. We intend to merge these two CLIs in future, but not today.

How does this new Gitpod CLI relate to the existing ‘Local Companion’? The Local Companion tool will now no longer be supported by Gitpod. Since we originally announced the Local Companion, we have since introduced other features which allow you to achieve similar behaviors previously offered by the Local Companion. See the Local Companion documentation for more.

Is the CLI compatible with all Gitpod IDEs and editors? Yes. The CLI allows you to open workspaces directly through SSH, the Browser Terminal, VS Code Desktop and Browser, or with any of the JetBrains IDEs.