https://github.com/opspresso/toast-cli
https://github.com/opspresso/toast-cli
aws cli git kubernetes pypi python toast
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/opspresso/toast-cli
- Owner: opspresso
- License: gpl-3.0
- Created: 2019-04-02T05:10:50.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2025-11-19T12:28:28.000Z (7 months ago)
- Last Synced: 2025-11-19T14:20:25.820Z (7 months ago)
- Topics: aws, cli, git, kubernetes, pypi, python, toast
- Language: Python
- Homepage: http://cli.toast.sh
- Size: 1.58 MB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# toast-cli
```
_ _ _ _
| |_ ___ __ _ ___| |_ ___| (_)
| __/ _ \ / _` / __| __|__ / __| | |
| || (_) | (_| \__ \ ||___| (__| | |
\__\___/ \__,_|___/\__| \___|_|_|
```
[](https://github.com/opspresso/toast-cli/actions/workflows/push.yml)
[](https://github.com/opspresso/toast-cli/releases)
[](https://pypi.org/project/toast-cli/)
[](https://cli.toast.sh/)
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](ARCHITECTURE.md) for details
## Installation
### Requirements
* Python 3.9+
* External tools: fzf, aws-cli, kubectl
* Python packages: click, rich
```bash
pyenv install 3.12
pyenv global 3.12.12
pyenv versions
```
### Install
### From PyPI
```bash
pip install toast-cli
```
### Or...
```bash
# 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
```bash
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
```bash
# 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:
```bash
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`
```bash
# 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
```python
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
```bash
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](CLAUDE.md) for guidelines
* **License**: [GNU GPL v3.0](LICENSE)
* **Contributing**: Via [GitHub repository](https://github.com/opspresso/toast-cli)
* **Documentation**: [ARCHITECTURE.md](ARCHITECTURE.md) and [toast.sh](https://cli.toast.sh/)