Gitpod CLI

👋 Hey! Are you looking for documentation on the gp CLI that runs in all workspaces?

You’re looking for the Gitpod Workspace CLI.

The Gitpod CLI is a command line interface for creating, managing and connecting to Gitpod workspaces either from your own device, or in automation, such as continuous integration.

language icon text
Available Commands:
  completion   Generate the autocompletion script for the specified shell
  config       Interact with the CLI's configuration
  help         Help about any command
  login        Logs the user in to the CLI
  organization Interact with organizations
  version      Prints the CLI version
  whoami       Produces information about the current user
  workspace    Interact with workspaces

Flags:
      --config string   Location of the configuration file (default "~/.gitpod/config.yaml")
  -h, --help            help for gitpod
  -v, --verbose         Display verbose output for more detailed logging

Use "gitpod [command] --help" for more information about a command.

Installation

To download and install the CLI, run the following commands:

Homebrew (macOS and Linux)

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

Direct Download (macOS, Linux, Windows)

We also offer direct download links to the binaries, which are portable and can be installed anywhere on your system. Note that this does not impact the auto-update functionality of the CLI.

Login with the Browser

When first starting getting started with the CLI, you’ll need to login. The gitpod login command will redirect you to your default browser where you can authenticate, before being redirected back to the CLI.

Login with an Access Token

Logging in with a token is particularly useful when you want to use the CLI in automation, such as in a CI pipeline or a remote server (including your Gitpod workspaces). To log in with an access token, proceed like so:

language icon bash
gitpod login --token <access-token>

Login to Enterprise

To log in to a host which is not gitpod.io, you can use the --host flag:

language icon bash
gitpod login --host <dedicated-host>

Choose an Organization (optional)

When you run gitpod whoami and the Organization you see is not the one you want to work with, you can change it as follows:

language icon bash
gitpod config set --organization-id <org-id>

Create and open a workspace in your editor

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

Create and connect to 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. You can list possible editor options with gitpod workspace list-editors.

Auto-update

You can print the current CLI version with gitpod version. The CLI automatically checks for updates and will notify you if a new one is available. You can disable this behavior by running gitpod config set --autoupdate=false.

To update, use gitpod version update.

Telemetry

By default, the CLI sends anonymous telemetry data to Gitpod, for both Dedicated and Cloud customers. We send this data so we can improve the experience of the CLI.

An example telemetry event looks like this:

language icon json
{
	"anonymousId": "edccf53037f5976beee2ac47dcaddd728235671d183ccbde15244d3012f90a3f",
	"event": "gitpodcli_command",
	"messageId": "e3c0f0f0-4b0d-11ec-9a1b-0242ac130003",
	"originalTimestamp": "2023-12-08T14:49:50.116635+01:00",
	"properties": {
		"command": "gitpod workspace create",
		"goarch": "arm64",
		"goos": "darwin",
		"version": "0.1.3"
	}
}

Data the Gitpod CLI does send

  • The CLI command name.
  • Exception information.
  • An anonymous machine ID.

Data the Gitpod CLI does not send

Any argument, flag or configuration, which includes (but is not limited to):

  • Personally identifying information.
  • Login information.
  • Repository names.
  • Branches.
  • SSH or connection information.

Disabling telemetry

If you wish to disable telemetry, you can do so by running the following. The CLI also respects the DO_NOT_TRACK environment variable.

language icon bash
gitpod config set --telemetry=false

Was this helpful?

Previous Next