CLI

Manage environments, SSH access, and automations from your terminal.

The CLI is being re-released with Ona branding. Until then, continue using gitpod as the command name.

Manage environments from your terminal - create, start, stop, SSH into environments, and run automations.

Installation

macOS and Linux

curl -o gitpod -fsSL "https://releases.gitpod.io/cli/stable/gitpod-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/\(arm64\|aarch64\)/arm64/')" && \
chmod +x gitpod && \
sudo mv gitpod /usr/local/bin

Direct download

Platform	Downloads
macOS	x86_64 | arm64
Linux	x86_64 | arm64
Windows	x86_64 | arm64

After downloading, make the binary executable and move it to your PATH:

chmod +x gitpod
sudo mv gitpod /usr/local/bin

macOS security warning

If macOS shows a security warning, approve the app in System Settings → Privacy & Security, or run:

xattr -d com.apple.quarantine gitpod

Verify download integrity

Option 1: SLSA Verification (Recommended)

SLSA verification cryptographically proves the CLI was built by the official build system:

# Set your platform
PLATFORM="linux-amd64"  # or darwin-amd64, darwin-arm64, etc.

# Download CLI package and attestation
curl -fsSL -O "https://releases.gitpod.io/cli/stable/gitpod-${PLATFORM}.tar.gz"
curl -fsSL -O "https://releases.gitpod.io/cli/stable/gitpod-${PLATFORM}.tar.gz.att"

# Download and run verification script
curl -fsSL -O https://releases.gitpod.io/cli/stable/verify-leeway-attestation.sh
chmod +x verify-leeway-attestation.sh
./verify-leeway-attestation.sh gitpod-${PLATFORM}.tar.gz

# Extract and install (only after verification passes)
tar -xzf gitpod-${PLATFORM}.tar.gz
chmod +x gitpod
sudo mv gitpod /usr/local/bin/

Option 2: Checksum Verification

Get the expected checksum:

curl -sL https://releases.gitpod.io/cli/stable/manifest.json | jq -r '.downloads["<platform>"].digest'

Calculate your file’s checksum and compare:

shasum -a 256 gitpod

Authentication

Browser login

gitpod login

Opens your browser to authenticate and stores credentials locally.

Personal access token

For CI/CD pipelines and scripts, use a personal access token:

gitpod login --token "your-token-here"

Or set the environment variable:

export GITPOD_TOKEN="your-token-here"
gitpod login

Inside Ona environments

The CLI is pre-installed and automatically authenticated with limited access. Run gitpod login to upgrade to full access.

When running inside an environment, the CLI automatically detects the current environment context. This means:

• Environment ID is inferred: Commands like gitpod automations, gitpod environment port, and other environment-specific commands work without requiring --environment-id
• Context preserved after login: When you run gitpod login inside an environment, the environment ID is preserved in your CLI context (as long as the login host matches the environment’s host). This allows you to continue using environment-specific commands after authentication.

# Inside an environment - no --environment-id needed
gitpod automations service list
gitpod environment port open 3000

# After running gitpod login, these still work without --environment-id
gitpod login
gitpod automations task start my-task

If you log into a different host than your environment (e.g., logging into app.gitpod.io from an environment on ona.e-corp.com), the environment ID will not be preserved.

Common commands

Command	Description
gitpod whoami	Show current user and access level
gitpod environment list	List your environments
gitpod environment create <repo-url>	Create a new environment
gitpod environment start <id>	Start an environment
gitpod environment stop <id>	Stop an environment
gitpod environment delete <id>	Delete an environment
gitpod environment ssh <id>	SSH into an environment
gitpod environment logs <id>	View environment logs

Use -o json or -o yaml for machine-readable output.

Using partial environment IDs

Instead of typing full UUIDs, you can use any substring of an environment ID:

# Full UUID
gitpod environment ssh 019194a6-f0b0-70a1-beae-99718c351b04

# Prefix
gitpod environment ssh 019194a6

# Suffix
gitpod environment ssh 351b04

# Any substring
gitpod environment ssh 70a1-beae

The CLI resolves the partial ID if it uniquely identifies an environment. If the substring matches multiple environments, you’ll see an error listing all matching IDs. If no environments match, you’ll be prompted to run gitpod environment list to see available environments.

SSH access

Configure SSH for direct access:

gitpod environment ssh-config

Then connect using:

ssh <environment-id>.gitpod.environment

You can also use partial environment IDs with the gitpod environment ssh command:

# Connect using a prefix instead of the full UUID
gitpod environment ssh 019194a6

# Or use any unique substring
gitpod environment ssh beae-997

For file transfers, use the -O flag:

scp -O <environment-id>.gitpod.environment:/workspaces/project/file.txt ./local-file.txt

Port management

gitpod environment port list
gitpod environment port open <port> --name "my-service"
gitpod environment port close <port>

Automation commands

gitpod automations init
gitpod automations update automations.yaml
gitpod automations task list
gitpod automations task start <task-reference>
gitpod automations task logs <task-reference>
gitpod automations service list
gitpod automations service start <service-reference>

Dotfiles management

Manage your dotfiles configuration directly from the CLI:

# View current dotfiles configuration
gitpod user dotfiles get

# Set dotfiles repository
gitpod user dotfiles set --repository https://github.com/user/dotfiles

# Clear dotfiles configuration
gitpod user dotfiles set

The get command supports output formats:

gitpod user dotfiles get -o json
gitpod user dotfiles get -o yaml

See dotfiles documentation for more information about using dotfiles with Ona.

Project and group management

gitpod project list
gitpod project create <repo-url>
gitpod group list
gitpod group create --name "Team Name"

Configuration

The CLI stores configuration at ~/.gitpod/configuration.yaml.

gitpod config context list
gitpod config context use <context-name>
gitpod config set --autoupdate=true

Shell completion

# Bash
gitpod completion bash > /etc/bash_completion.d/gitpod

# Zsh
gitpod completion zsh > "${fpath[1]}/_gitpod"

# Fish
gitpod completion fish > ~/.config/fish/completions/gitpod.fish

Updates

gitpod version
gitpod version update

Troubleshooting

Authentication issues

gitpod login --non-interactive  # For headless environments
gitpod login --token "<token>"  # Use token directly

SSH connection failures

If you see too many authentication failures, add to ~/.ssh/gitpod/config:

Host *.gitpod.environment
    IdentitiesOnly yes

Debug with:

ssh -vvv <environment-id>.gitpod.environment

Run gitpod help or add --help to any command for more information.