A beautiful command-line interface for managing the Forkspacer Kubernetes operator. Create, manage, and hibernate ephemeral development environments with style.
- Overview
- Features
- Installation
- Quick Start
- Commands
- Examples
- Shell Completion
- Configuration
- Development
- Contributing
- License
The Forkspacer CLI is part of the Forkspacer ecosystem, which consists of:
- Forkspacer Operator - Core Kubernetes operator managing custom resources
- API Server - Backend API service (optional)
- Operator UI - Web-based dashboard (optional)
- CLI (this project) - Command-line interface
The CLI provides direct Kubernetes integration, beautiful terminal output, and fast client-side validation.
┌─────────────────────────────────────────────┐
│ Kubernetes Cluster │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Forkspacer │◄────►│ Workspaces │ │
│ │ Operator │ │ & Modules │ │
│ │ (CRD Watch) │ │ (CRDs) │ │
│ └──────────────┘ └──────────────┘ │
│ ▲ │
│ │ │
│ │ kubectl-style access │
└─────────┼───────────────────────────────────┘
│
┌─────▼──────┐
│ Forkspacer │◄─── You
│ CLI │
└────────────┘
- 🎨 Beautiful Output - Styled terminal output with colors, spinners, and progress indicators
- ⚡ Fast Validation - Client-side validation for instant feedback
- 🚀 Easy to Use - Intuitive commands that feel natural
- 🔧 Shared Business Logic - Uses Forkspacer API server library for consistent operations
- 🌍 Cross-Platform - Works on macOS, Linux, and Windows
- 📝 Shell Completion - Tab completion for bash, zsh, fish, and powershell
- 🔄 Workspace Lifecycle - Create, hibernate, wake, and manage workspaces
- ⏰ Auto-Hibernation - Schedule workspaces to sleep and wake automatically
- Kubernetes cluster (1.24+)
- Forkspacer Operator installed in your cluster
kubectlconfigured with cluster access
The quickest way to install (macOS & Linux):
curl -sSL https://raw.githubusercontent.com/forkspacer/cli/main/scripts/install.sh | bashcurl -sSL https://github.com/forkspacer/cli/releases/latest/download/forkspacer-darwin-arm64.tar.gz | tar xz
sudo mv forkspacer /usr/local/bin/curl -sSL https://github.com/forkspacer/cli/releases/latest/download/forkspacer-darwin-amd64.tar.gz | tar xz
sudo mv forkspacer /usr/local/bin/curl -sSL https://github.com/forkspacer/cli/releases/latest/download/forkspacer-linux-amd64.tar.gz | tar xz
sudo mv forkspacer /usr/local/bin/curl -sSL https://github.com/forkspacer/cli/releases/latest/download/forkspacer-linux-arm64.tar.gz | tar xz
sudo mv forkspacer /usr/local/bin/Download forkspacer-windows-amd64.zip from the releases page, extract, and add to your PATH.
git clone https://github.com/forkspacer/cli.git
cd cli
go build -o forkspacer .
sudo mv forkspacer /usr/local/bin/forkspacer version# List existing workspaces
forkspacer workspace list
# Create a simple workspace
forkspacer workspace create dev-env
# Create with auto-hibernation (sleep at 6 PM, wake at 8 AM)
forkspacer workspace create dev-env \
--hibernation-schedule "0 18 * * *" \
--wake-schedule "0 8 * * *"
# Get detailed workspace information
forkspacer workspace get dev-env
# Hibernate a workspace manually
forkspacer workspace hibernate dev-env
# Wake up a hibernated workspace
forkspacer workspace wake dev-env
# Delete a workspace
forkspacer workspace delete dev-env --force
# Use short alias
forkspacer ws list# Create
forkspacer workspace create <name> [flags]
--hibernation-schedule string Cron schedule for auto-hibernation
--wake-schedule string Cron schedule for auto-wake
--connection string Connection type (default "in-cluster")
--from string Fork from existing workspace
--wait Wait for workspace to be ready
# List
forkspacer workspace list [flags]
--all-namespaces, -A List workspaces across all namespaces
# Get
forkspacer workspace get <name>
# Delete
forkspacer workspace delete <name> [flags]
--force Skip confirmation prompt
# Hibernate
forkspacer workspace hibernate <name>
# Wake
forkspacer workspace wake <name>
# Alias
forkspacer ws <command> # Short form for workspace commands-n, --namespace string Kubernetes namespace (default "default")
-o, --output string Output format: table|json|yaml (default "table")
-v, --verbose Enable verbose output
-h, --help Help for any command# Show version
forkspacer version
# Generate shell completion
forkspacer completion [bash|zsh|fish|powershell]$ forkspacer workspace create my-dev-env
✨ Creating workspace my-dev-env
✓ Workspace name is valid
✓ Connected to cluster (context: minikube)
✓ Forkspacer operator is installed
✓ Workspace name is available
✓ Workspace resource created
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Name: my-dev-env
Namespace: default
Type: kubernetes
Hibernation: disabled
Next steps:
→ forkspacer workspace get my-dev-env
→ forkspacer module deploy redis --workspace my-dev-env
Documentation: https://forkspacer.com/docs/workspaces$ forkspacer workspace create staging \
--hibernation-schedule "0 18 * * 1-5" \
--wake-schedule "0 8 * * 1-5"
# Workspace will automatically:
# - Hibernate at 6 PM on weekdays
# - Wake up at 8 AM on weekdays$ forkspacer workspace list
┌──────────┬───────────┬────────────┬───────┬────────────┬─────────────────────┐
│ NAME │ NAMESPACE │ PHASE │ READY │ HIBERNATED │ LAST ACTIVITY │
├──────────┼───────────┼────────────┼───────┼────────────┼─────────────────────┤
│ dev-env │ default │ ready │ true │ false │ 2025-10-09 18:40:59 │
│ staging │ default │ hibernated │ true │ true │ 2025-10-09 12:30:00 │
└──────────┴───────────┴────────────┴───────┴────────────┴─────────────────────┘
Total: 2 workspace(s)# Create workspace in specific namespace
forkspacer workspace create prod-env -n production
# List all workspaces across namespaces
forkspacer workspace list --all-namespacesCommon hibernation schedules:
# Every day at 6 PM
--hibernation-schedule "0 18 * * *"
# Weekdays at 6 PM
--hibernation-schedule "0 18 * * 1-5"
# Every Monday at 9 AM
--hibernation-schedule "0 9 * * 1"
# Every 15 minutes
--hibernation-schedule "*/15 * * * *"
# Every Sunday at midnight
--hibernation-schedule "0 0 * * 0"Enable tab completion for faster command entry:
# Linux
forkspacer completion bash > /etc/bash_completion.d/forkspacer
# macOS
forkspacer completion bash > /usr/local/etc/bash_completion.d/forkspacer# macOS (Homebrew)
forkspacer completion zsh > $(brew --prefix)/share/zsh/site-functions/_forkspacer
# Linux
forkspacer completion zsh > /usr/local/share/zsh/site-functions/_forkspacer
# Then restart your shell
exec zshforkspacer completion fish > ~/.config/fish/completions/forkspacer.fishforkspacer completion powershell | Out-String | Invoke-ExpressionAfter enabling completion, you can:
forkspacer work<TAB> # → workspace
forkspacer workspace cr<TAB> # → create
forkspacer ws li<TAB> # → listThe CLI uses your ~/.kube/config for Kubernetes authentication. Configure your context:
# View current context
kubectl config current-context
# Switch context
kubectl config use-context my-cluster
# List available contexts
kubectl config get-contexts- Go 1.25 or later
- Kubernetes cluster for testing
- Forkspacer Operator installed
# Clone the repository
git clone https://github.com/forkspacer/cli.git
cd cli
# Install dependencies
go mod download
# Build
go build -o forkspacer .
# Run
./forkspacer versioncli/
├── cmd/ # Command implementations
│ ├── root.go # Root command & global flags
│ ├── version.go # Version command
│ └── workspace/ # Workspace commands
│ ├── create.go
│ ├── list.go
│ ├── get.go
│ ├── delete.go
│ ├── hibernate.go
│ └── wake.go
├── pkg/ # Shared packages
│ ├── workspace/ # Workspace service wrapper (delegates to api-server)
│ ├── printer/ # Output formatting (tables, spinners)
│ ├── styles/ # Terminal styling (colors, layouts)
│ └── validation/ # Input validation (DNS, cron)
├── .github/ # GitHub workflows & templates
├── scripts/ # Install scripts
└── main.go # Entry point
The CLI imports the Forkspacer API server's service layer as a library, providing a unified approach to workspace operations:
api-server/pkg/services/forkspacer (shared business logic)
↓ ↓
HTTP Handlers CLI Wrapper Service
(for REST API) (pkg/workspace/)
↓
CLI Commands
Benefits:
- Single source of truth for business logic
- Type-safe compile-time checking
- No network overhead for CLI operations
- Consistent validation and error handling
- Shared code maintenance between API and CLI
# Run tests
go test -v ./...
# Run tests with coverage
go test -v -race -coverprofile=coverage.out ./...
# View coverage
go tool cover -html=coverage.out# macOS (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o forkspacer-darwin-arm64 .
# macOS (Intel)
GOOS=darwin GOARCH=amd64 go build -o forkspacer-darwin-amd64 .
# Linux
GOOS=linux GOARCH=amd64 go build -o forkspacer-linux-amd64 .
# Windows
GOOS=windows GOARCH=amd64 go build -o forkspacer-windows-amd64.exe .We welcome contributions! Please see CONTRIBUTING.md for details on:
- Code of Conduct
- Development workflow
- Submitting pull requests
- Coding standards
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
go test ./...) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- ✅ Workspace CRUD operations
- ✅ Hibernation/Wake commands
- ✅ Beautiful terminal output
- ✅ Shell completion
- 🚧 Module management commands
- 🚧 Helm chart deployment
- 🚧 Resource filtering
- 📋 Helm release discovery
- 📋 Batch import existing releases
- 📋 Interactive init wizard
- 📋 Workspace forking
- 📋 Full feature parity with operator capabilities
- 📋 Advanced output formats (JSON, YAML)
- 📋 Plugin system
- 📋 Enhanced error handling
# Check kubectl connectivity
kubectl cluster-info
# Check current context
kubectl config current-context
# Verify Forkspacer operator is installed
kubectl get crd workspaces.batch.forkspacer.com# Check RBAC permissions
kubectl auth can-i create workspaces.batch.forkspacer.com
# View your permissions
kubectl auth can-i --list# Use verbose mode to see detailed errors
forkspacer workspace create my-env --verbose
# Check operator logs
kubectl logs -n operator-system deployment/operator-controller-managerThis project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- Built with Cobra for CLI framework
- Styled with Lipgloss for beautiful output
- Powered by controller-runtime
Made with ❤️ by the Forkspacer Team
⭐ Star us on GitHub if you find this project useful!