mirror of
https://github.com/gitpod-io/gitpod.git
synced 2025-12-08 17:36:30 +00:00
1bc35eb6e1
* [memory bank] Initialize cline memory bank Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Start documenting first components (blobserve, content-service, dashboard, ws-manager-mk2) Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Document more components (supervisor, ws-daemon) Tool: gitpod/catfood.gitpod.cloud * [memory-bank] More components (ide-service, registry-facade, image-builder-mk3) Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Document proxy, server and ws-proxy Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Document gitpod-cli and gitpod-db Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Document gitpod-protocol Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Document ide-proxy, ide and ws-manager-bridge Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Document ide-metrics and local-app Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Document public-api-serverr and usage Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Document common-go and workspacekit Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Document spicedb, scrubber and service-waiter Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Documented docker-up, image-builder-bob, node-labeler Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Documented openvsx-proxy, scheduler-extender, ipfs Tool: gitpod/catfood.gitpod.cloud * [memory-bank] Update rules to lay out the "components" structure Tool: gitpod/catfood.gitpod.cloud
144 lines
5.0 KiB
Markdown
144 lines
5.0 KiB
Markdown
# Gitpod CLI Component
|
|
|
|
## Overview
|
|
|
|
The Gitpod CLI (Command Line Interface) is a utility that comes pre-installed within Gitpod workspaces, providing users with a convenient way to interact with the Gitpod platform and control various aspects of their workspace environment from the terminal.
|
|
|
|
## Purpose
|
|
|
|
The primary purposes of the Gitpod CLI are:
|
|
- Provide a command-line interface for interacting with Gitpod workspaces
|
|
- Enable users to control workspace features and settings
|
|
- Facilitate IDE integration from the terminal
|
|
- Manage workspace ports and port forwarding
|
|
- Control environment variables
|
|
- Manage workspace lifecycle
|
|
- Coordinate task execution
|
|
- Provide authentication and credential management
|
|
- Enable workspace snapshots
|
|
- Support workspace configuration
|
|
|
|
## Architecture
|
|
|
|
The Gitpod CLI is implemented as a Go application with a command-based structure using the Cobra command framework. It consists of several key components:
|
|
|
|
1. **Command Processor**: Handles command parsing and execution
|
|
2. **Supervisor Client**: Communicates with the workspace supervisor
|
|
3. **Analytics Tracker**: Tracks command usage for analytics
|
|
4. **Error Reporter**: Reports errors to the supervisor
|
|
5. **Credential Helper**: Manages Git credentials
|
|
|
|
The CLI is designed to be lightweight and efficient, providing a simple interface to the more complex functionality provided by the workspace supervisor.
|
|
|
|
## Key Files and Structure
|
|
|
|
- `main.go`: Entry point that calls the Execute function from the cmd package
|
|
- `cmd/root.go`: Defines the root command and basic CLI configuration
|
|
- `cmd/*.go`: Individual command implementations
|
|
- `pkg/gitpod/`: Gitpod-specific functionality
|
|
- `pkg/utils/`: Utility functions
|
|
|
|
## Commands
|
|
|
|
The Gitpod CLI provides a wide range of commands:
|
|
|
|
### Workspace Management
|
|
- `gp stop`: Stop the current workspace
|
|
- `gp snapshot`: Take a snapshot of the current workspace
|
|
- `gp init`: Create a Gitpod configuration for the current project
|
|
- `gp url`: Print the URL of the current workspace
|
|
|
|
### IDE Integration
|
|
- `gp open`: Open a file in the IDE
|
|
- `gp preview`: Open a URL in the IDE's preview
|
|
|
|
### Port Management
|
|
- `gp ports`: List all exposed ports
|
|
- `gp ports expose`: Make a port available on 0.0.0.0
|
|
- `gp ports await`: Wait for a process to listen on a port
|
|
- `gp ports visibility`: Set the visibility of a port
|
|
- `gp ports protocol`: Set the protocol of a port
|
|
|
|
### Task Management
|
|
- `gp tasks`: List all tasks
|
|
- `gp tasks attach`: Attach to a running task
|
|
- `gp tasks stop`: Stop a running task
|
|
|
|
### Environment Variables
|
|
- `gp env`: Manage user-defined environment variables
|
|
|
|
### Synchronization
|
|
- `gp sync-await`: Wait for an event to happen
|
|
- `gp sync-done`: Signal that an event has happened
|
|
|
|
### Authentication
|
|
- `gp credential-helper`: Git credential helper
|
|
- `gp idp`: Identity provider integration
|
|
|
|
### Timeout Management
|
|
- `gp timeout`: Manage workspace timeout
|
|
- `gp timeout set`: Set workspace timeout
|
|
- `gp timeout show`: Show workspace timeout
|
|
- `gp timeout extend`: Extend workspace timeout
|
|
|
|
### Information
|
|
- `gp info`: Show information about the workspace
|
|
- `gp user-info`: Show information about the user
|
|
|
|
## Dependencies
|
|
|
|
### Internal Dependencies
|
|
- `components/supervisor-api/go:lib`: Supervisor API definitions
|
|
- `components/gitpod-protocol/go:lib`: Gitpod protocol definitions
|
|
- `components/common-go:lib`: Common Go utilities
|
|
- `components/ide-metrics-api/go:lib`: IDE metrics API definitions
|
|
- `components/public-api/go:lib`: Public API definitions
|
|
|
|
### External Dependencies
|
|
- Cobra for command-line interface
|
|
- Logrus for logging
|
|
- Various Go standard libraries
|
|
|
|
## Integration Points
|
|
|
|
The Gitpod CLI integrates with:
|
|
1. **Supervisor**: Communicates with the workspace supervisor for most operations
|
|
2. **Git**: Provides credential helper for Git authentication
|
|
3. **IDE**: Opens files and previews in the IDE
|
|
4. **Workspace**: Manages workspace lifecycle and configuration
|
|
5. **Identity Providers**: Integrates with various identity providers for authentication
|
|
|
|
## Error Handling
|
|
|
|
The CLI implements sophisticated error handling:
|
|
- User-friendly error messages
|
|
- Error reporting to the supervisor
|
|
- Error logging for debugging
|
|
- Different exit codes for different error types
|
|
|
|
## Analytics
|
|
|
|
The CLI includes analytics tracking to help improve the user experience:
|
|
- Tracks command usage
|
|
- Records command outcomes
|
|
- Measures command duration
|
|
- Reports errors (with user consent)
|
|
|
|
## Common Usage Patterns
|
|
|
|
The Gitpod CLI is typically used to:
|
|
1. Open files in the IDE: `gp open file.txt`
|
|
2. Preview URLs: `gp preview https://example.com`
|
|
3. Expose ports: `gp ports expose 8080`
|
|
4. Manage environment variables: `gp env NAME=VALUE`
|
|
5. Coordinate task execution: `gp sync-await event && command`
|
|
6. Take workspace snapshots: `gp snapshot`
|
|
7. Stop the workspace: `gp stop`
|
|
|
|
## Related Components
|
|
|
|
- **Supervisor**: Provides the API that the CLI uses to interact with the workspace
|
|
- **IDE**: Receives commands from the CLI to open files and previews
|
|
- **Server**: Manages workspace lifecycle and configuration
|
|
- **Workspace**: The environment in which the CLI operates
|