Package Exports

@butterfly-security/cli
@butterfly-security/cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@butterfly-security/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🦋 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:

Browser opens automatically to https://butterflysecurity.org/login
Choose your login method: Google, GitHub, Microsoft, GitLab, or Email
Complete authentication in your browser
Token automatically sent to the CLI
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: support@butterflysecurity.org

License

MIT License - see LICENSE for details.