Gitpod CLI

The Gitpod CLI is a powerful tool that allows you to interact with your Ona environments and manage your development workflow directly from the terminal. Whether you’re starting new environments, managing existing ones, or configuring your workspace, the CLI provides a streamlined interface for all your operations.

Installation

Getting started with the Gitpod CLI is straightforward. You have two options:

Option 1: Quick Install (UNIX Systems - macOS, Linux)

This one-line installation method works for macOS and Linux systems:

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

Option 2: Direct Download

Choose the appropriate version for your system:

macOS: x86_64 | arm64
Linux: x86_64 | arm64
Windows: x86_64 | arm64

After downloading, you’ll need to:

Make the binary executable:
```
chmod +x gitpod
```
Move it to your PATH:
```
sudo mv gitpod /usr/local/bin
```

Note for macOS users: When first running a downloaded binary, you may see a security warning.

You can resolve this by either: Approving the app in System Settings → Privacy & Security Or removing the quarantine attribute via terminal:

xattr -d com.apple.quarantine gitpod

The binary’s signature can be verified using:

codesign -v gitpod -vvv

Verifying Download Integrity

For security, verify the integrity of your downloaded CLI binary using SHA256 checksums from our release manifest:

# Get the checksums for the current release
curl https://releases.gitpod.io/cli/stable/manifest.json -L

Verification Steps

Get the expected checksum for your platform:

# Extract checksum for your platform (requires jq)
curl -sL https://releases.gitpod.io/cli/stable/manifest.json | jq -r '.downloads["<platform>"].digest'

# Examples:
# macOS Intel:        .downloads["darwin-amd64"].digest
# macOS Apple Silicon: .downloads["darwin-arm64"].digest  
# Linux x86_64:       .downloads["linux-amd64"].digest
# Windows x86_64:     .downloads["windows-amd64"].digest

Calculate your file’s checksum:

# macOS/Linux
shasum -a 256 gitpod

# Windows PowerShell
Get-FileHash gitpod-windows-amd64.exe -Algorithm SHA256

Compare the checksums - they must match exactly.

Security Warning: If the checksums don’t match, do not use the binary and re-download from the official source.

Without jq

If you don’t have jq installed, view the full manifest and manually find your platform’s digest:

curl https://releases.gitpod.io/cli/stable/manifest.json -L

Getting started with Gitpod CLI

Authentication

The Gitpod CLI supports multiple authentication methods:

Automated Authentication (in Ona Environments)

When using the CLI in an Ona environment, it automatically authenticates using the environment’s token. Check your authentication status:

gitpod whoami

The output shows your access level:

PRINCIPAL_ENVIRONMENT: Limited access to current environment only
Your username: Full access to all features and environments

Browser-based Authentication

gitpod login

This is the simplest method that will:

Open your default browser for authentication
Create a new context for your session
Store your credentials securely

Personal Access Token Authentication

For headless environments or automation scenarios, you can authenticate using a Personal Access Token:

gitpod login --token

You can also provide the token directly:

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

Environment Variables

Set the GITPOD_TOKEN environment variable before logging in:

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

CLI in Ona Environments

Pre-installed CLI

Every Ona environment comes with the Gitpod CLI pre-installed as gitpod. The CLI is automatically authenticated with limited access to the current environment’s context, allowing you to:

Stop the current environment (gitpod environment stop)
View environment logs (gitpod environment logs)
Rebuild the development container (gitpod devcontainer rebuild)

Upgrading Environment Access

To access additional features like managing other environments or organization resources, you’ll need to create a new, fully authenticated context:

From within your environment, run:
```
gitpod login
```
After authentication, the new context will automatically activate, giving you access to:
- All environment management commands
- Organization settings
- Project management
- Automation controls
- Secret management

Remember that this upgraded access persists only for the current environment session. You’ll need to re-authenticate if you restart the environment.

Access Levels and Authentication Scope

Depending on how you’re logged in, you may have different access levels. You can always change your authentication method or scope using the gitpod login command.

Default Environment Access (Pre-authenticated)

View current environment status
Basic environment operations
Local development container management
Port forwarding

Create and manage all environments
Organization management
Project creation and configuration
Secret management
Automation control
Runner management
Cross-environment operations

Basic Commands

Here are some essential commands to get you started:

# View your user information
gitpod whoami

# List your environments
gitpod environment list

# Create a new environment
gitpod environment create <repository-url>

# Start an existing environment
gitpod environment start <environment-id>

# Stop an environment
gitpod environment stop <environment-id>

# Delete an environment
gitpod environment delete <environment-id>

Machine-readable Output

For scripting and automation, you can get machine-readable output in JSON or YAML format:

gitpod environment list -o json
gitpod environment list -o yaml

Core Features

Environment Management

Creating Environments

gitpod environment create <repo-url> [flags]

# Common flags:
--class-id        # Specify environment class
--editor          # Choose your preferred editor
--interactive     # Use interactive mode
--set-as-context  # Set as active context

Working with Running Environments

# SSH into an environment
gitpod environment ssh <environment-id>

# View environment logs
gitpod environment logs <environment-id>

# List environment ports
gitpod environment port list

# Open a port
gitpod environment port open <port-number>

# Open a port with HTTPS backend protocol
gitpod environment port open <port-number> --name "my-service" --protocol https

# List available editors
gitpod environment list-editors

# Open with an editor
gitpod environment open <environment-id> --editor <editor-name|editor-id>

Automation Management

The CLI provides comprehensive automation management capabilities:

# Initialize new automation
gitpod automations init

# Update automations of an environment
gitpod automations update automations.yaml

# Update the default automation file of an environment
gitpod automations update -s .gitpod/automations.yaml

# List automation tasks
gitpod automations task list

# Start a task
gitpod automations task start <task-reference>

# View task logs
gitpod automations task logs <task-reference>

# List automation services
gitpod automations service list

# Start a task
gitpod automations service start <service-reference>

# View task logs
gitpod automations service logs <service-reference>

Advanced Features

SSH Configuration

Set up native SSH access to your environments:

gitpod environment ssh-config

After configuration, connect directly using:

ssh <environment-id>.gitpod.environment

File Transfer with SCP

To transfer files to and from your environments using SCP, you must use the -O flag to ensure compatibility:

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

Example: Copy a README.md file from an environment to your local machine:

scp -O 01992e7a-b263-75d8-8956-87335d4b0ba3.gitpod.environment:/workspaces/website/README.md R.md

Important: The -O flag is required when using SCP with Gitpod environments. Without this flag, file transfers may fail or behave unexpectedly.

Project Management

# List projects
gitpod project list

# Get project details
gitpod project get <project-id>

# Create a new project
gitpod project create <repo-url>

Port Management

# Open a port with a custom name
gitpod environment port open <port> --name "my-service"

# Open a port with HTTPS backend protocol
gitpod environment port open <port> --name "my-service" --protocol https

# Close a port
gitpod environment port close <port>

Context Management

# List available contexts
gitpod config context list

# Switch contexts
gitpod config context use <context-name>

# Modify context settings
gitpod config context modify <context-name>

Global Configuration

The CLI configuration file is located at ~/.gitpod/configuration.yaml. You can modify settings using:

gitpod config set [flags]

# Common configuration options:
--autoupdate        # Enable/disable automatic updates
--release-channel   # Set release channel (stable/latest)
--host              # Set Ona instance host

Best Practices

Context Management
- Use separate contexts for different projects or organizations
- Name contexts meaningfully for easy identification
Environment Lifecycle
- Stop unused environments to conserve resources
- Use --dont-wait flags for batch operations
- Set appropriate timeouts for long-running operations
Automation
- Initialize automation files in your project root
- Use descriptive task names
- Monitor task logs for debugging
Security
- Regularly rotate access tokens
- Use environment-specific SSH keys
- Keep the CLI updated for security patches

Troubleshooting

Common issues and solutions:

Authentication Issues

gitpod login --non-interactive  # For environments without browser access
gitpod login --token "<your-token>"  # Use a token directly
gitpod config context modify --token "<your-token>"  # Update token manually

Connection Problems

gitpod environment logs --include-system-logs --raw # View detailed logs
gitpod environment ssh --verbose  # Debug SSH connections
ssh -vvv <environment-id>.gitpod.environment  # Debug SSH connections

Too Many SSH Authentication Failures

If you encounter too many authentication failures when connecting to a Gitpod environment, it may be due to multiple SSH keys being offered by an agent (e.g., 1Password). The server rejects connections after six failed attempts. Solutions:

Stop the SSH agent to prevent other keys from being offered.
Ensure only the CLI key is used by adding IdentitiesOnly yes to your ~/.ssh/gitpod/config under the Host *.gitpod.environment section.

Testing:

Re-enable your SSH agent and test the connection:

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

Ensure the correct key (Offering public key:) is used.

Shell Completion

Enable shell completion for easier CLI usage:

# 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

# PowerShell
gitpod completion powershell | Out-String | Invoke-Expression

Updates and Maintenance

Keep your CLI up to date:

# Check version
gitpod version

# Update CLI
gitpod version update

# Force update (even if version is up-to-date)
gitpod version update --force

Additional Resources

Use gitpod help for comprehensive command documentation
Add -h or --help to any command for specific usage information
Use --verbose flag for detailed logging when troubleshooting
Check the configuration file at ~/.gitpod/configuration.yaml for custom settings

Remember that the CLI is constantly evolving with new features and improvements. Keep your installation updated and refer to the official documentation for the latest information.

Quickstart

Ona Environments

Ona Agents

Ona Guardrails

Deployment

Editors & IDEs

Organizations

Projects

Integrations

Source Control

​Installation

​Option 1: Quick Install (UNIX Systems - macOS, Linux)

​Option 2: Direct Download

​Verifying Download Integrity

​Verification Steps

​Without jq

​Getting started with Gitpod CLI

​Authentication

​Automated Authentication (in Ona Environments)

​Browser-based Authentication

​Personal Access Token Authentication

​Environment Variables

​CLI in Ona Environments

​Pre-installed CLI

​Upgrading Environment Access

​Access Levels and Authentication Scope

​Default Environment Access (Pre-authenticated)

​Full Authentication Access (After Login)

​Basic Commands

​Machine-readable Output

​Core Features

​Environment Management

​Creating Environments

​Working with Running Environments

​Automation Management

​Advanced Features

​SSH Configuration

​File Transfer with SCP

​Project Management

​Port Management

​Context Management

​Global Configuration

​Best Practices

​Troubleshooting

​Authentication Issues

​Connection Problems

​Too Many SSH Authentication Failures

​Testing:

​Shell Completion

​Updates and Maintenance

​Additional Resources

Installation

Option 1: Quick Install (UNIX Systems - macOS, Linux)

Option 2: Direct Download

Verifying Download Integrity

Verification Steps

Without jq

Getting started with Gitpod CLI

Authentication

Automated Authentication (in Ona Environments)

Browser-based Authentication

Personal Access Token Authentication

Environment Variables

CLI in Ona Environments

Pre-installed CLI

Upgrading Environment Access

Access Levels and Authentication Scope

Default Environment Access (Pre-authenticated)

Full Authentication Access (After Login)

Basic Commands

Machine-readable Output

Core Features

Environment Management

Creating Environments

Working with Running Environments

Automation Management

Advanced Features

SSH Configuration

File Transfer with SCP

Project Management

Port Management

Context Management

Global Configuration

Best Practices

Troubleshooting

Authentication Issues

Connection Problems

Too Many SSH Authentication Failures

Testing:

Shell Completion

Updates and Maintenance

Additional Resources