🦋 Butterfly CLI

Okta backup and recovery from your terminal. The official CLI for Butterfly Security.

Installation

Homebrew (macOS/Linux)

brew tap butterfly-security/tap
brew install butterfly

npm (Node.js)

npm install -g @butterfly-security/cli

Binary Download

Download pre-built binaries from the releases page.

Quick Start

# Authenticate using OAuth (recommended)
butterfly login

# Check status of your Okta orgs
butterfly status

# Create a backup
butterfly backup

# List recent backups
butterfly list

# Select a backup to work with
butterfly select

# Compare changes between backups
butterfly diff

# Export as Terraform
butterfly export terraform

# Export to Git repository
butterfly export git

New! Butterfly now supports modern OAuth device flow authentication. Simply run butterfly login and your browser opens automatically. No API keys or manual copy/paste needed! See Authentication for details.

Commands

Authentication

Modern OAuth Device Flow (Recommended):

butterfly login                    # OAuth login - browser opens automatically
butterfly logout                   # Clear credentials
butterfly status                   # Show authentication status

Legacy API Key (Still Supported):

butterfly login --api-key KEY      # Login with API key (for backward compatibility)

How OAuth Works

When you run butterfly login:

1. Browser opens automatically to https://butterflysecurity.org/login
2. Choose your login method: Google, GitHub, Microsoft, GitLab, or Email
3. Complete authentication in your browser
4. Token automatically sent to the CLI
5. You're logged in! No manual copy/paste needed

If your browser doesn't open, the CLI will show a device code that you can manually enter at https://butterflysecurity.org/cli/authorize.

Backup Operations

butterfly backup                   # Trigger new backup
butterfly backup --wait            # Wait for completion
butterfly backup -r users,groups   # Backup specific resources
butterfly list                     # List all backups
butterfly list --limit 20          # Show more backups
butterfly list --json              # JSON output

Select & Focus

butterfly select                   # Interactive backup selection
butterfly select abc123            # Select by ID
butterfly selected                 # Show current selection
butterfly select --clear           # Clear selection

Diff & Compare

butterfly diff                     # Compare latest two backups
butterfly diff --from ID1 --to ID2 # Compare specific backups
butterfly diff --type users        # Filter by resource type

Export

# Terraform
butterfly export terraform
butterfly export tf --output ./my-terraform

# Git
butterfly export git               # Interactive Git export

# JSON
butterfly export json

Configuration

butterfly config show              # Show configuration
butterfly config set apiUrl URL    # Set API URL
butterfly config set defaultOrg ID # Set default org
butterfly config edit              # Interactive config
butterfly config reset             # Reset to defaults

Watch Mode

butterfly watch                    # Continuous monitoring
butterfly watch --interval 30      # Check every 30 minutes

Output Formats

Most commands support --json for machine-readable output:

butterfly status --json
butterfly list --json
butterfly diff --json

Environment Variables

• BUTTERFLY_API_KEY - API key for authentication
• BUTTERFLY_API_URL - Custom API URL (default: https://butterflysecurity.org)

Configuration File

Configuration is stored in:

• macOS: ~/Library/Application Support/butterfly-cli/config.json
• Linux: ~/.config/butterfly-cli/config.json
• Windows: %APPDATA%\butterfly-cli\config.json

Example configuration:

{
  "accessToken": "eyJhbGc...",
  "tokenType": "Bearer",
  "expiresAt": 1707456789000,
  "apiUrl": "https://butterflysecurity.org",
  "defaultOrg": "your-okta-org",
  "selectedBackup": null
}

Note: OAuth tokens are stored securely on your computer and automatically managed by the CLI. You can safely ignore this file - the CLI handles everything for you.

Examples

Daily Backup Script

#!/bin/bash
# Backup and export to Git daily
butterfly backup --wait
butterfly export git --backup latest

CI/CD Integration

# GitHub Actions
- name: Backup Okta Configuration
  run: |
    npm install -g @butterfly-security/cli
    butterfly login --api-key ${{ secrets.BUTTERFLY_API_KEY }}
    butterfly backup --wait
    butterfly export terraform --output ./terraform

Watch for Drift

# Monitor for changes and alert
butterfly watch --interval 60 2>&1 | tee backup.log

What's New

v2.0+ Features

✨ OAuth Device Flow Authentication

• Modern browser-based login
• Automatic token delivery to CLI
• No manual copy/paste needed
• Supports Google, GitHub, Microsoft, GitLab, Email
• Tokens auto-expire after 1 hour for security

🔐 Enhanced Security

• OAuth tokens more secure than static API keys
• Automatic token expiration
• One-time token delivery

🔄 Backward Compatibility

• API keys still work for legacy integrations
• No breaking changes to CLI commands
• Existing scripts continue to work

📚 Better Documentation

• Full CLI authentication guide at https://butterflysecurity.org/docs#cli-auth
• Step-by-step examples
• Troubleshooting guide

Support

• Documentation: https://butterflysecurity.org/docs#cli-auth
• GitHub Issues: https://github.com/butterfly-security/cli/issues
• Email: [email protected]

License

MIT License - see LICENSE for details.