toast-cli 4.0.3

A Python-based CLI utility with a plugin architecture for AWS, Kubernetes, Git, and more

toast-cli

 _                  _           _ _
| |_ ___   __ _ ___| |_     ___| (_)
| __/ _ \ / _` / __| __|__ / __| | |
| || (_) | (_| \__ \ ||___| (__| | |
 \__\___/ \__,_|___/\__|   \___|_|_|

Python-based CLI utility with plugin architecture for AWS, Kubernetes, and Git operations.

Features

• Plugin Architecture: Modular design with dynamic command discovery
• AWS Integration: Identity checking, profile management, region selection, SSM Parameter Store integration
• Kubernetes: Context switching, EKS cluster discovery and integration, context deletion
• Git: Repository management (clone, branch, pull, push, mirror), organization-specific GitHub hosts
• Workspace: Directory navigation, environment file management (.env.local, .prompt.md)
• Interface: FZF-powered interactive menus, formatted output with Rich
• Security: AWS SSM SecureString storage for sensitive files

Architecture

• Commands implemented as plugins extending BasePlugin
• Automatic plugin discovery and loading
• Click integration for CLI behavior
• See ARCHITECTURE.md for details

Installation

Requirements

• Python 3.9+
• External tools: fzf, aws-cli, kubectl
• Python packages: click, rich

pyenv install 3.12
pyenv global 3.12.12
pyenv versions

Install

From PyPI

pip install toast-cli

Or...

# From GitHub
pip install git+https://github.com/opspresso/toast-cli.git

# Development mode
git clone https://github.com/opspresso/toast-cli.git
cd toast-cli
pip install -e .

Usage

toast --help         # View available commands
toast am             # Show AWS identity
toast cdw            # Navigate workspace directories
toast ctx            # Manage Kubernetes contexts
toast dot            # Manage .env.local files
toast env            # Manage AWS profiles
toast git            # Manage Git repositories
toast prompt         # Manage .prompt.md files
toast region         # Manage AWS region
toast ssm            # AWS SSM Parameter Store operations
toast version        # Display version

Examples

# AWS
toast am                   # Show identity
toast env                  # Switch profiles
toast region               # Switch regions

# Kubernetes
toast ctx                  # Switch contexts
# Select [New...] to add EKS clusters from current region
# Select [Del...] to delete contexts (individual or all)

# Environment Files (.env.local)
toast dot                  # Compare local and SSM, choose action (default: sync)
toast dot up               # Upload .env.local to SSM
toast dot down             # Download .env.local from SSM (alias: dn)
toast dot ls               # List all .env.local files in SSM

# Prompt Files (.prompt.md)
toast prompt               # Compare local and SSM, choose action (default: sync)
toast prompt up            # Upload .prompt.md to SSM
toast prompt down          # Download .prompt.md from SSM (alias: dn)
toast prompt ls            # List all .prompt.md files in SSM

# SSM Parameter Store
toast ssm                  # Interactive mode: browse and select parameters
toast ssm ls               # List all parameters
toast ssm ls /toast/       # List parameters under path
toast ssm get /my/param    # Get parameter value (alias: g)
toast ssm put /my/param 'value'  # Store as SecureString (alias: p)
toast ssm rm /my/param     # Delete parameter (alias: d, delete)

# Git Operations
toast git repo-name clone                    # Clone repository
toast git repo-name branch -b branch-name    # Create branch
toast git repo-name pull                     # Pull changes
toast git repo-name pull -r                  # Pull with rebase
toast git repo-name push                     # Push to remote
toast git repo-name push -f                  # Force push
toast git repo-name push --mirror            # Mirror push for migration

Workspace Structure

Toast-cli uses a standardized workspace directory structure for organizing projects:

~/workspace/{github-host}/{org}/{project}

Examples:

• ~/workspace/github.com/opspresso/toast-cli
• ~/workspace/github.enterprise.com/myorg/myproject

First-time Setup:

When you run toast cdw for the first time, it will automatically:

1. Create ~/workspace directory if it doesn't exist
2. Create ~/workspace/github.com as the default structure
3. Display instructions for creating organization and project directories

You can then create your project directories:

mkdir -p ~/workspace/github.com/{org}/{project}

Benefits:

• Consistent project organization across all Git hosts
• Automatic detection of GitHub host per organization
• Seamless integration with other toast-cli commands (git, dot, prompt)

Configuration

GitHub Host Configuration

Configure custom GitHub hosts for different organizations by creating .toast-config files:

File location: ~/workspace/github.com/{org}/.toast-config

# For organization-specific hosts
echo "GITHUB_HOST=github.enterprise.com" > ~/workspace/github.com/myorg/.toast-config

# For custom SSH hosts (useful for different accounts)
echo "GITHUB_HOST=myorg-github.com" > ~/workspace/github.com/myorg/.toast-config

Example SSH config (~/.ssh/config):

Host myorg-github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_rsa_myorg

Benefits:

• Different GitHub Enterprise hosts per organization
• Different SSH keys and accounts per organization
• Automatic host detection based on workspace location
• Seamless switching between GitHub accounts

AWS SSM Storage Paths

Toast-cli stores files in AWS SSM Parameter Store with the following structure:

/toast/local/{org}/{project}/env-local     # .env.local files
/toast/local/{org}/{project}/prompt-md     # .prompt.md files

Files are stored as SecureString type for encryption at rest.

Creating Plugins

1. Create a file in toast/plugins/
2. Extend BasePlugin
3. Implement required methods
4. Set name and help variables

from toast.plugins.base_plugin import BasePlugin
import click

class MyPlugin(BasePlugin):
    name = "mycommand"
    help = "Command description"

    @classmethod
    def get_arguments(cls, func):
        func = click.option("--option", "-o", help="Option description")(func)
        return func

    @classmethod
    def execute(cls, **kwargs):
        option = kwargs.get("option")
        click.echo(f"Executing with option: {option}")

Aliases

alias t='toast'
c() { cd "$(toast cdw)" }    # Navigate to workspace
alias m='toast am'           # AWS identity
alias x='toast ctx'          # Kubernetes contexts
alias d='toast dot'          # .env.local files
alias p='toast prompt'       # .prompt.md files
alias e='toast env'          # AWS profiles
alias g='toast git'          # Git repositories
alias r='toast region'       # AWS region
alias s='toast ssm'          # SSM Parameter Store

Resources

• Development: See CLAUDE.md for guidelines
• License: GNU GPL v3.0
• Contributing: Via GitHub repository
• Documentation: ARCHITECTURE.md and toast.sh