terminus-golang

Terminus Go

A command-line interface for managing Pantheon sites, written in Go. This is a complete rewrite of the Pantheon Terminus CLI tool.

Until a 1.0.0 release, this package may contain code that is both AI generated and not fully tested. See Implementation Status to see what commands have been implemented and which ones have been fully tested by a human. In this project, "Human Tested" means that the code has been evaluated line-by-line with a step debugger and we feel confident in running that command against production Pantheon accounts.

Features

• Command-line Interface: Full-featured CLI for managing Pantheon sites, environments, workflows, and more
• Go API Package: Standalone Go package for programmatic access to the Pantheon API
• Multiple Output Formats: Table, JSON, YAML, CSV, and list formats
• Comprehensive Commands: Support for all major Pantheon operations
• Session Management: Secure token storage and session handling
• Workflow Management: Monitor and wait for asynchronous operations

Installation

From Source

go install github.com/pantheon-systems/terminus-go/cmd/terminus@latest

Build Manually

git clone https://github.com/pantheon-systems/terminus-go.git
cd terminus-go
go build -o terminus ./cmd/terminus

Quick Start

Authentication

First, log in with your machine token:

terminus auth:login --machine-token=YOUR_TOKEN --email=your@email.com

List Your Sites

terminus site list

Get Site Information

terminus site info my-site

List Environments

terminus env list my-site

Deploy to Test

terminus env deploy my-site.test

Create a Backup

terminus backup create my-site.live

Available Commands

Authentication

• auth:login - Log in to Pantheon
• auth:logout - Log out of Pantheon
• auth:whoami - Show current user information

Site Management

• site list - List all sites
• site info <site> - Show site information
• site create <name> - Create a new site
• site delete <site> - Delete a site
• site team list <site> - List team members

Environment Management

• env list <site> - List environments
• env info <site>.<env> - Show environment information
• env clear-cache <site>.<env> - Clear environment cache
• env deploy <site>.<env> - Deploy code to an environment
• env clone-content <site>.<env> - Clone database/files between environments
• env commit <site>.<env> - Commit changes in SFTP mode
• env wipe <site>.<env> - Wipe environment content
• env connection set <site>.<env> <mode> - Set connection mode (git/sftp)

Workflow Management

• workflow list <site> - List workflows
• workflow info <site> <workflow-id> - Show workflow information
• workflow wait <site> <workflow-id> - Wait for a workflow to complete
• workflow watch <site> <workflow-id> - Watch a workflow with live updates

Backup Management

• backup list <site>.<env> - List backups
• backup create <site>.<env> - Create a backup
• backup get <site>.<env> - Download a backup
• backup restore <site>.<env> - Restore from a backup
• backup automatic info <site>.<env> - Show backup schedule
• backup automatic enable <site>.<env> - Enable automatic backups
• backup automatic disable <site>.<env> - Disable automatic backups

Organization Management

• org list - List organizations
• org info <org> - Show organization information
• org people list <org> - List organization members
• org site list <org> - List organization sites
• org upstreams list <org> - List organization upstreams

Domain Management

• domain list <site>.<env> - List domains
• domain add <site>.<env> <domain> - Add a domain
• domain remove <site>.<env> <domain> - Remove a domain
• domain dns <site>.<env> <domain> - Show DNS recommendations

Multidev Management

• multidev create <site>.<multidev> - Create a multidev environment
• multidev delete <site>.<multidev> - Delete a multidev environment
• multidev merge-to-dev <site>.<multidev> - Merge multidev to dev
• multidev merge-from-dev <site>.<multidev> - Merge dev into multidev

Global Flags

• --format - Output format (table, json, yaml, csv, list)
• --fields - Comma-separated list of fields to display
• --yes, -y - Answer yes to all prompts
• --quiet, -q - Suppress output
• --verbose, -v - Verbose output

Output Formats

Table (Default)

terminus site list

JSON

terminus site list --format=json

YAML

terminus site info my-site --format=yaml

CSV

terminus site list --format=csv

Field Filtering

terminus site list --fields=name,id,framework

Configuration

Terminus Go supports multiple configuration sources (in priority order):

1. Environment variables (TERMINUS_*)
2. .env file in current directory
3. User config file (~/.terminus/config.yml)
4. Default values

Configuration File

Create ~/.terminus/config.yml:

TERMINUS_HOST: terminus.pantheon.io
TERMINUS_PORT: 443
TERMINUS_PROTOCOL: https
TERMINUS_TIMEOUT: 86400

Environment Variables

export TERMINUS_HOST=terminus.pantheon.io
export TERMINUS_CACHE_DIR=~/.terminus/cache

Using as a Go Package

Terminus Go can be used as a library in your Go applications:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/pantheon-systems/terminus-go/pkg/api"
    "github.com/pantheon-systems/terminus-go/pkg/session"
)

func main() {
    // Create API client
    client := api.NewClient(
        api.WithToken("your-session-token"),
    )

    // Create services
    sitesService := api.NewSitesService(client)

    // List sites
    ctx := context.Background()
    sites, err := sitesService.List(ctx)
    if err != nil {
        log.Fatal(err)
    }

    for _, site := range sites {
        fmt.Printf("Site: %s (%s)\n", site.Name, site.ID)
    }
}

API Services

The following services are available:

• AuthService - Authentication operations
• SitesService - Site management
• EnvironmentsService - Environment operations
• WorkflowsService - Workflow monitoring
• BackupsService - Backup management
• OrganizationsService - Organization management
• DomainsService - Domain management
• MultidevService - Multidev operations

Development

Prerequisites

• Go 1.24 or higher
• golangci-lint
• pre-commit and golanci-linter (optional)

Setup

# Clone repository
git clone https://github.com/pantheon-systems/terminus-go.git
cd terminus-go

# Install dependencies
go mod download

# Build
go build -o bin/terminus ./cmd/terminus

# Run tests
go test ./...

# Run linter
golangci-lint run

Install Pre-commit Hooks

pre-commit install
pre-commit install --hook-type commit-msg

Running Tests

# Run all tests
go test ./...

# Run with coverage
go test ./... -coverprofile=coverage.out

# View coverage
go tool cover -html=coverage.out

Project Structure

terminus-go/
├── cmd/
│   └── terminus/          # CLI entry point
├── pkg/
│   ├── api/              # Pantheon API client (public)
│   │   ├── client.go     # HTTP client
│   │   ├── auth.go       # Authentication
│   │   ├── sites.go      # Sites API
│   │   ├── environments.go
│   │   ├── workflows.go
│   │   ├── backups.go
│   │   ├── organizations.go
│   │   ├── domains.go
│   │   ├── multidev.go
│   │   └── models/       # API data models
│   ├── config/           # Configuration management
│   ├── session/          # Session/token storage
│   └── output/           # Output formatting
├── internal/
│   └── commands/         # CLI commands (private)
└── test/
    └── fixtures/         # Test fixtures

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (go test ./...)
5. Run linter (golangci-lint run)
6. Commit your changes using conventional commits
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Conventional Commits

This project uses Conventional Commits for automated changelog generation:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• test: - Test changes
• refactor: - Code refactoring
• chore: - Maintenance tasks

License

MIT License

Acknowledgments

• Original Pantheon Terminus project
• Cobra - CLI framework
• Viper - Configuration management

Support

For issues and questions:

• GitHub Issues: https://github.com/pantheon-systems/terminus-go/issues
• Pantheon Documentation: https://pantheon.io/docs

Differences from PHP Terminus

While this Go version aims for feature parity with the PHP Terminus, there are some differences:

1. Performance: Go version is faster due to compiled nature
2. Binary Distribution: Single binary with no runtime dependencies
3. API Package: Go version provides a standalone API package for programmatic use
4. Configuration: Simplified configuration with fewer layers
5. Plugin System: Not yet implemented (planned for future release)

Roadmap

• Core API client
• Authentication commands
• Site management
• Environment operations
• Workflow management
• Backup operations
• Organization management
• Domain management
• Multidev operations
• HTTPS/SSL management
• Connection info commands
• SSH key management
• Import/export operations
• New Relic integration
• Redis/Solr management
• Plugin system
• Shell completion
• Man page generation

Implementation Status

This section tracks the implementation status of all PHP Terminus commands in this Go version. Commands are compared against PHP Terminus 3.x.

Legend:

• ✅ = Implemented / Tested
• ❌ = Not implemented / Not tested

aliases

Command	Description	Implemented	Human Tested
aliases	Print all site aliases	❌	❌

art

Command	Description	Implemented	Human Tested
art	Display Pantheon ASCII art	✅	✅
art:list	List available ASCII art	✅	✅

auth

Command	Description	Implemented	Human Tested
auth:login	Log in to Pantheon using a machine token	✅	✅
auth:logout	Log out of Pantheon and delete saved session	✅	✅
auth:whoami	Display current user information	✅	✅

backup

Command	Description	Implemented	Human Tested
backup:automatic:disable	Disable automatic backups for an environment	✅	❌
backup:automatic:enable	Enable automatic backups for an environment	✅	❌
backup:automatic:info	Show automatic backup schedule	✅	❌
backup:create	Create a backup of an environment	✅	❌
backup:get	Download a specific backup	✅	❌
backup:info	Show information about a specific backup	✅	❌
backup:list	List backups for an environment	✅	❌
backup:restore	Restore an environment from a backup	✅	❌

branch

Command	Description	Implemented	Human Tested
branch:list	List git branches for a site	✅	❌

connection

Command	Description	Implemented	Human Tested
connection:info	Show connection info for an environment	✅	❌
connection:set	Set connection mode (git/sftp)	✅	❌

dashboard

Command	Description	Implemented	Human Tested
dashboard:view	Open site dashboard in a browser	✅	✅

domain

Command	Description	Implemented	Human Tested
domain:add	Add a domain to an environment	✅	❌
domain:dns	Show DNS recommendations for a domain	✅	❌
domain:list	List domains for an environment	✅	❌
domain:lookup	Find the site associated with a domain	❌	❌
domain:primary:add	Add a primary domain to an environment	❌	❌
domain:primary:remove	Remove primary domain designation	❌	❌
domain:remove	Remove a domain from an environment	✅	❌

env

Command	Description	Implemented	Human Tested
env:clear-cache	Clear caches for an environment	✅	❌
env:clone-content	Clone database and/or files between environments	✅	❌
env:code-log	Show code log for an environment	❌	❌
env:code-rebuild	Rebuild code for an environment	❌	❌
env:commit	Commit changes in SFTP mode	✅	❌
env:deploy	Deploy code to an environment	✅	❌
env:diffstat	Show diff statistics for an environment	❌	❌
env:info	Show environment information	✅	❌
env:list	List environments for a site	✅	❌
env:metrics	Show environment metrics	✅	✅
env:rotate-random-seed	Rotate the Drupal hash salt	❌	❌
env:view	Open environment in a browser	❌	❌
env:wake	Wake a sleeping environment	❌	❌
env:wipe	Wipe database and files from an environment	✅	❌

https

Command	Description	Implemented	Human Tested
https:info	Show HTTPS/SSL information	❌	❌
https:remove	Remove HTTPS certificate	❌	❌
https:set	Enable HTTPS with a certificate	❌	❌

import

Command	Description	Implemented	Human Tested
import:complete	Complete site import	❌	❌
import:database	Import database to an environment	❌	❌
import:files	Import files to an environment	❌	❌
import:site	Import a site archive	❌	❌

local

Command	Description	Implemented	Human Tested
local:clone	Clone a Pantheon site locally	❌	❌
local:commitAndPush	Commit and push local changes	❌	❌
local:dockerize	Create Docker setup for local development	❌	❌
local:getLiveDB	Download database from live environment	❌	❌
local:getLiveFiles	Download files from live environment	❌	❌

lock

Command	Description	Implemented	Human Tested
lock:disable	Disable HTTP basic auth for an environment	✅	❌
lock:enable	Enable HTTP basic auth for an environment	✅	❌
lock:info	Show lock status for an environment	✅	❌

machine-token

Command	Description	Implemented	Human Tested
machine-token:delete	Delete a machine token	❌	❌
machine-token:delete-all	Delete all machine tokens	❌	❌
machine-token:list	List machine tokens	✅	❌

multidev

Command	Description	Implemented	Human Tested
multidev:create	Create a multidev environment	✅	❌
multidev:delete	Delete a multidev environment	✅	❌
multidev:list	List multidev environments	✅	❌
multidev:merge-from-dev	Merge code from dev into multidev	✅	❌
multidev:merge-to-dev	Merge code from multidev to dev	✅	❌

new-relic

Command	Description	Implemented	Human Tested
new-relic:disable	Disable New Relic for a site	❌	❌
new-relic:enable	Enable New Relic for a site	❌	❌
new-relic:info	Show New Relic information	❌	❌

org

Command	Description	Implemented	Human Tested
org:info	Show organization information	✅	❌
org:list	List organizations	✅	❌
org:people:list	List organization members	✅	❌
org:site:list	List sites belonging to an organization	✅	❌
org:upstream:list	List upstreams for an organization	✅	❌

owner

Command	Description	Implemented	Human Tested
owner:set	Change site owner	❌	❌

payment-method

Command	Description	Implemented	Human Tested
payment-method:add	Add a payment method	❌	❌
payment-method:list	List payment methods	✅	❌
payment-method:remove	Remove a payment method	❌	❌

plan

Command	Description	Implemented	Human Tested
plan:info	Show site plan information	✅	❌
plan:list	List available plans	✅	❌
plan:set	Change the site plan	❌	❌

redis

Command	Description	Implemented	Human Tested
redis:disable	Disable Redis for a site	✅	❌
redis:enable	Enable Redis for a site	✅	❌

remote

Command	Description	Implemented	Human Tested
drush	Run a Drush command on a site	❌	❌
wp	Run a WP-CLI command on a site	❌	❌

self

Command	Description	Implemented	Human Tested
self:clear-cache	Clear Terminus cache	❌	❌
self:config:dump	Dump Terminus configuration	❌	❌
self:console	Open interactive console	❌	❌
self:info	Show Terminus information	✅	❌
self:plugin:create	Create a new plugin	❌	❌
self:plugin:install	Install a plugin	❌	❌
self:plugin:list	List installed plugins	❌	❌
self:plugin:reload	Reload plugins	❌	❌
self:plugin:search	Search for plugins	❌	❌
self:plugin:uninstall	Uninstall a plugin	❌	❌
self:plugin:update	Update a plugin	❌	❌

service-level

Command	Description	Implemented	Human Tested
service-level:set	Set the service level of a site	❌	❌

site

Command	Description	Implemented	Human Tested
site:create	Create a new site	✅	❌
site:delete	Delete a site	✅	❌
site:info	Show site information	✅	❌
site:label	Set site label	❌	❌
site:list	List sites	✅	✅
site:lookup	Look up a site by UUID	❌	❌
site:org:add	Add site to an organization	❌	❌
site:org:list	List organizations a site belongs to	✅	❌
site:org:remove	Remove site from an organization	❌	❌
site:team:add	Add a user to the site team	❌	❌
site:team:list	List site team members	✅	❌
site:team:remove	Remove a user from the site team	❌	❌
site:team:role	Change a team member's role	❌	❌
site:upstream:clear-cache	Clear upstream cache	❌	❌
site:upstream:set	Set the upstream for a site	❌	❌

solr

Command	Description	Implemented	Human Tested
solr:disable	Disable Solr for a site	❌	❌
solr:enable	Enable Solr for a site	❌	❌

ssh-key

Command	Description	Implemented	Human Tested
ssh-key:add	Add an SSH key to your account	❌	❌
ssh-key:list	List SSH keys on your account	✅	❌
ssh-key:remove	Remove an SSH key from your account	❌	❌

tag

Command	Description	Implemented	Human Tested
tag:add	Add a tag to a site	❌	❌
tag:list	List tags for a site	✅	❌
tag:remove	Remove a tag from a site	❌	❌

upstream

Command	Description	Implemented	Human Tested
upstream:info	Show upstream information	✅	❌
upstream:list	List upstreams	✅	❌
upstream:updates:apply	Apply upstream updates to a site	❌	❌
upstream:updates:list	List available upstream updates	✅	❌
upstream:updates:status	Check for upstream updates	❌	❌

workflow

Command	Description	Implemented	Human Tested
workflow:info	Show workflow information	✅	❌
workflow:list	List workflows for a site	✅	❌
workflow:wait	Wait for a workflow to complete	✅	❌
workflow:watch	Watch a workflow with live progress	✅	❌

Implementation Summary

Status	Count
Total Commands	113
Implemented	48
Not Implemented	65
Implementation Progress	42%