Gitpod Command Line Interface (CLI)

The Gitpod CLI is a powerful tool that allows you to interact with your Gitpod 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 Gitpod operations.

Installation

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

Option 1: Quick Install (UNIX Systems)

Option 2: Direct Download

Choose the appropriate version for your system:

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

Getting Started

Authentication

The Gitpod CLI supports multiple authentication methods to suit different usage scenarios:

Browser-based Authentication

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:

You can also provide the token directly:

Environment Variables

Set the GITPOD_TOKEN environment variable before logging in:

CLI in Gitpod Environments

Pre-installed CLI

Every Gitpod environment comes with the 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:

1. From within your environment, run:

   bash

   gitpod login

2. 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

Full Authentication Access (After Login)

• 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:

Machine-readable Output

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

Core Features

Environment Management

Creating Environments

Working with Running Environments

Automation Management

The CLI provides comprehensive automation management capabilities:

Advanced Features

SSH Configuration

Set up native SSH access to your environments:

After configuration, connect directly using:

Project Management

Port Management

Context Management

Global Configuration

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

Best Practices

1. Context Management

   • Use separate contexts for different projects or organizations
   • Name contexts meaningfully for easy identification

2. Environment Lifecycle

   • Stop unused environments to conserve resources
   • Use --dont-wait flags for batch operations
   • Set appropriate timeouts for long-running operations

3. Automation

   • Initialize automation files in your project root
   • Use descriptive task names
   • Monitor task logs for debugging

4. Security

   • Regularly rotate access tokens
   • Use environment-specific SSH keys
   • Keep the CLI updated for security patches

Troubleshooting

Common issues and solutions:

1. Authentication Issues

   bash

   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

2. Connection Problems

   bash

   gitpod environment logs --include-system-logs --raw # View detailed logs
   gitpod environment ssh --verbose  # Debug SSH connections

Shell Completion

Enable shell completion for easier CLI usage:

Updates and Maintenance

Keep your CLI up to date:

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.