Opus CLI

An internal DevEx CLI tool that provides a unified entry point for development teams, integrating internal infrastructure (GKE, GCP, GitHub Actions, Preview Env, Secret Manager) to improve development experience and operational efficiency.

Features

• 🚀 Unified Access - Single entry point for GKE, GCP, GitHub Actions, Preview Env, Secret Manager
• 🔐 Multi-Platform Authentication - Support for GCP, GitHub, and Lark (OAuth)
• 📦 Single Binary - Cross-platform support (macOS, Linux)
• 🎨 Rich TUI - K9s-style table interface for GitHub operations
• ⚡ Fast Operations - Quick deployment and debugging tools
• 🎯 Standardized Workflows - Consistent internal processes

Installation

Build from Source

# Clone the repository
git clone <repository-url>
cd opus-cli

# Build
make build

# Or use go directly
go build -o opus ./cmd/opus/main.go

Using Homebrew (Coming Soon)

brew install opus-cli/tap/opus

Quick Start

# Authenticate with a provider
opus login --provider github

# View current user
opus whoami

# Browse GitHub repositories
opus github repos

# View pull requests
opus github prs

# View workflow runs
opus github actions

# Open GCP console
opus open --gcp

# View preview environments
opus preview list

# Trigger deployment
opus deploy trigger --service my-service --env staging

Commands

Authentication

• opus login - Authenticate with a provider (GCP, GitHub, Lark)
• opus whoami - Display current authenticated user information
• opus init - Initialize configuration for providers

GitHub Operations

• opus github repos - Browse and manage GitHub repositories
• opus github prs - View and manage pull requests
• opus github issues - View and manage issues
• opus github actions - View and manage workflow runs

GitHub TUI Features

The GitHub commands feature a rich terminal user interface (TUI) with:

Repository Browser:

• Browse repositories with inline action menus
• Quick access to PRs, Issues, and Actions
• Filter and search capabilities

Pull Requests:

• K9s-style table view with columns: Status, #, Title, Author, Branch, Updated, +/-, Checks
• Filter by state (all, open, closed, merged)
• Sort by updated, created, title, or author
• Quick actions: merge, close, reopen
• View PR details, comments, files, commits, diffs, and check runs
• Multi-select mode for batch operations

Issues:

• Full TUI support for browsing and managing issues
• View issue details and comments
• Filter and sort capabilities

Workflow Runs (Actions):

• K9s-style table view with columns: Status, Workflow, #, Branch, Actor, Updated, Duration
• Filter by status (all, queued, in_progress, completed, failed)
• Filter by workflow type
• Sort by updated, created, name, or status
• Quick actions: cancel, rerun, rerun failed jobs
• View job details and logs
• Workflow type selection popup

Common Features:

• Header bar showing repository, totals, and filter status (K9s-style)
• Keyboard shortcuts for all operations
• Inline action menus (no page refreshes)
• Error messages displayed within TUI
• Browser integration (ctrl+o to open in browser)

Infrastructure

• opus preview - Manage preview environments
• opus deploy - Deployment operations
• opus k8s - Kubernetes operations
• opus secret - Secret Manager operations
• opus open - Open web consoles (GCP/GitHub)

Utility

• opus version - Display version information

Configuration

Configuration file location: ~/.opus/config.yml

Supports multiple profiles. Use the --profile flag to switch between profiles.

Environment Variables

You can configure providers using environment variables:

• GITHUB_TOKEN - GitHub Personal Access Token
• LARK_APP_ID - Lark App ID
• LARK_APP_SECRET - Lark App Secret
• GCP_PROJECT_ID - GCP Project ID

See ENV_CONFIG.md for detailed configuration options.

Keyboard Shortcuts

GitHub TUI Navigation

General:

• ↑↓ / k/j - Navigate up/down
• Enter / v - View actions menu
• q / ESC - Quit/Go back
• ctrl+o - Open in browser
• ctrl+r - Refresh list

Pull Requests:

• f - Toggle filter (all → open → closed → merged)
• s - Toggle sort (updated → created → title → author)
• m - Quick merge PR
• c - Quick close PR
• r - Quick reopen PR
• space - Toggle multi-select mode

Workflow Runs:

• f - Toggle filter (all → queued → in_progress → completed → failed)
• s - Toggle sort (updated → created → name → status)
• g - Show workflow type selection popup
• x - Quick cancel run
• R - Quick rerun workflow

Project Structure

opus-cli/
├── cmd/                  # CLI command definitions
│   ├── opus/            # Main entry point
│   ├── login.go         # Authentication
│   ├── whoami.go        # User info
│   ├── github.go        # GitHub operations
│   ├── k8s/             # Kubernetes commands
│   ├── deploy/          # Deployment commands
│   ├── preview/         # Preview environment commands
│   └── secret/          # Secret Manager commands
├── internal/            # Internal implementation
│   ├── auth/            # Authentication module
│   │   ├── provider.go  # Provider interface
│   │   ├── gcp.go       # GCP authentication
│   │   ├── github.go    # GitHub authentication
│   │   └── lark.go      # Lark authentication
│   ├── config/          # Configuration management
│   ├── infra/           # Infrastructure layer
│   │   ├── gcp/         # GCP integration
│   │   ├── github/      # GitHub integration
│   │   └── k8s/         # Kubernetes integration
│   ├── ui/              # User interface components
│   │   ├── table_wrapper.go    # Base table component
│   │   ├── action_table.go     # Actions table view
│   │   ├── pr_table.go          # PRs table view
│   │   ├── repo_browser.go      # Repository browser
│   │   ├── repo_detail.go       # PR/Issue/Action lists
│   │   ├── pr_views.go           # PR detail views
│   │   ├── issue_views.go        # Issue views
│   │   ├── detail_view.go        # Detail views
│   │   └── ...                  # Other UI components
│   └── logging/         # Logging module
├── pkg/                 # Reusable public packages
│   └── utils/           # Utility functions
└── scripts/             # Build scripts

Development

Prerequisites

• Go 1.22+
• Make (optional)

Development Environment with Nix

This project supports Nix Shell for a reproducible development environment. Nix Shell helps ensure:

• ✅ Consistent Tool Versions - All developers use the same Go, golangci-lint, and other tool versions
• ✅ Reproducible Builds - Eliminates "works on my machine" issues
• ✅ Isolated Environment - No pollution of your system with project-specific tools
• ✅ CI/CD Consistency - Development and CI environments match exactly
• ✅ Quick Setup - New developers can start immediately without manual tool installation

Using Nix Shell (Traditional)

# Enter the Nix shell
nix-shell

# Now you have access to all tools (go, golangci-lint, make, etc.)
make build
make test
make lint

Using Nix Flakes (Recommended)

Option 1: Manual activation (temporary)

# Manually enter the development shell
nix develop

# Exit with Ctrl+D or 'exit'

Option 2: Automatic activation with direnv (recommended)

# Install direnv first
brew install direnv

# Add to ~/.zshrc:
eval "$(direnv hook zsh)"

# Reload shell
source ~/.zshrc

# In the project directory, approve .envrc
direnv allow

# Now the environment activates automatically when you enter the directory
# and deactivates when you leave

Without Nix

If you prefer not to use Nix, you can install the tools manually:

• Go 1.22+ from https://golang.org/dl/
• golangci-lint from https://golangci-lint.run/usage/install/
• Make (usually pre-installed on macOS/Linux)

Building

make build          # Build for current platform
make build-all      # Build for all platforms
make test           # Run tests
make lint           # Run linter

Architecture

The project follows a clean architecture pattern:

1. Command Layer (cmd/) - CLI command definitions using Cobra
2. Service Layer (internal/services/) - Business logic
3. Infrastructure Layer (internal/infra/) - External service integrations
4. UI Layer (internal/ui/) - Terminal user interface components
5. Auth Layer (internal/auth/) - Authentication providers

UI Components

The TUI is built using:

• Bubble Tea - TUI framework
• Bubbles - TUI components (list, table)
• Lipgloss - Styling

Key Design Decisions

1. Shared Table Component - BaseTableModel provides common table functionality, while each view (PRs, Actions) defines its own columns and data transformations
2. Inline Menus - Action menus appear inline without page refreshes
3. Error Handling - All errors are displayed within the TUI, not printed to terminal
4. State Management - Each view manages its own state (filtering, sorting, selection)

Roadmap

Completed ✅

• Multi-provider authentication (GCP, GitHub, Lark)
• GitHub repository browser
• GitHub Pull Requests TUI with table view
• GitHub Issues TUI
• GitHub Actions/Workflow Runs TUI with table view
• K9s-style table interface
• Inline action menus
• Filtering and sorting
• Quick actions (merge, close, cancel, rerun)
• Workflow type filtering
• Header information bar

In Progress 🚧

• Column sorting in table view
• Column width adjustment
• Column show/hide functionality
• Full-select/deselect for batch operations
• Pagination information display

Planned 📋

• Code review features
• Notifications management
• Branch management
• Enhanced search capabilities
• Customizable keyboard shortcuts
• Theme customization
• Export functionality (CSV, JSON)
• Integration with local Git repositories
• Preview environment management
• Deployment automation
• Kubernetes resource management
• Secret Manager integration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

[To be determined]