Gitpod 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:
After downloading, you’ll need to:
-
Make the binary executable:
Move it to your PATH:
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:
The binary’s signature can be verified using:
Getting started with Gitpod CLI
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:
-
From within your environment, run:
-
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
-
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
Connection Problems
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 theHost *.gitpod.environment
section.
Testing:
Re-enable your SSH agent and test the connection:
Ensure the correct key (Offering public key:
) is used.
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.
Was this page helpful?