CrunchyCone CLI

Command-line interface for managing CrunchyCone projects and deployments.

Installation

From npm

npm install -g crunchycone-cli

Or run directly with npx:

npx crunchycone-cli auth login

Global Options

The CLI supports several global flags that can be used with any command:

# Disable animations and spinners (useful for CI/CD)
crunchycone-cli --quiet auth whoami
crunchycone-cli -q project builds

# JSON output format (machine-readable)
crunchycone-cli --json project status
crunchycone-cli -j env list

# Verbose mode for debugging API requests
crunchycone-cli --verbose database upload ./app.db
crunchycone-cli -v auth whoami

From source

cd cli/crunchycone-cli
npm install
npm run build
npm link

Usage

Authentication

First, authenticate with your CrunchyCone account:

# Login via Google OAuth
crunchycone-cli auth login

# Check current authenticated user
crunchycone-cli auth whoami

# Logout
crunchycone-cli auth logout

# Logout and revoke API key on server
crunchycone-cli auth logout --revoke

Configuration

The CLI stores configuration in:

• API Keys: Securely stored in system keychain (macOS Keychain, Windows Credential Vault, Linux Secret Service)
• Config: ~/.config/crunchycone-cli/ (non-sensitive data)

Custom API URL

For development or self-hosted instances:

crunchycone-cli auth login --api-url http://localhost:3000

Development

Setup

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev -- auth whoami

# Run tests
npm test

Project Structure

src/
├── index.ts           # CLI entry point
├── commands/
│   └── auth.ts       # Authentication commands
└── lib/
    ├── api.ts        # API client
    ├── config.ts     # Configuration management
    └── types.ts      # TypeScript types

Authentication Flow

1. crunchycone-cli auth login starts a local server on port 8989
2. Opens browser to CrunchyCone OAuth login
3. After successful authentication, browser redirects to localhost:8989/callback
4. CLI exchanges temporary token for long-lived API key
5. API key is stored securely in system keychain

Security

• API keys are stored in the system's secure credential storage
• No sensitive data is stored in plain text
• OAuth flow uses state parameter for CSRF protection
• Local callback server only accepts one request then shuts down

Project Management

Manage your CrunchyCone projects directly from the CLI:

# Link current directory to a project
crunchycone-cli project link <project-id> --name "My Project"

# Remove project link
crunchycone-cli project unlink

# Show current project status
crunchycone-cli project status

# List recent builds (default: 5)
crunchycone-cli project builds

# List specific number of builds
crunchycone-cli project builds --limit 10

# View build logs for a specific build
crunchycone-cli project builds log <build-id>

# Use with project ID override (bypasses crunchycone.toml)
crunchycone-cli project --project-id <project-id> builds
crunchycone-cli project --project-id <project-id> builds log <build-id>

# Show build details
crunchycone-cli project build <build-id>

# Promote build to production
crunchycone-cli project promote <build-id>

# Manage custom domains
crunchycone-cli project domains
crunchycone-cli project add-domain example.com

# Set project environment
crunchycone-cli project set-env production

# Show project information
crunchycone-cli project info

# View project configuration
crunchycone-cli project config

Build Management

Monitor and manage your project builds directly from the CLI:

# List recent builds (shows last 5 by default)
crunchycone-cli project builds

# List more builds
crunchycone-cli project builds --limit 20

# View detailed build logs for debugging
crunchycone-cli project builds log <build-id>

# Use quiet mode for CI/CD scripts
crunchycone-cli --quiet project builds log <build-id>

# JSON output for automation and scripts
crunchycone-cli --json project builds --limit 10
crunchycone-cli --json project builds log <build-id>

# Work with specific project (bypasses crunchycone.toml)
crunchycone-cli project --project-id 01234567-89ab-cdef-0123-456789abcdef builds
crunchycone-cli project --project-id 01234567-89ab-cdef-0123-456789abcdef builds log <build-id>

View Build Logs

crunchycone-cli project builds log <build-id> [options]

Options:

• --mark-fixing: Mark this failed build as being actively fixed before showing logs

Example:

# View logs and mark as being fixed
crunchycone-cli project builds log abc-123 --mark-fixing

This is useful when agents or developers start working on fixing a failed build, providing visibility into which failures are being addressed.

Build Information Displayed:

• Complete Build ID (full UUID, no truncation)
• Build status with color coding (success: green, failed: red, running: yellow)
• Commit SHA and branch information
• Build creation timestamps
• Professional table formatting with proper column alignment

Build Log Features:

• Complete pipeline execution logs with full GitLab CI/CD details
• Formatted output with timestamps and job separation
• ANSI color code support for readability
• Detailed build metadata (commit message, pipeline ID, execution times)
• Error highlighting and debugging information
• JSON output support for automation and CI/CD integration

Environment Variables Management

Manage platform environment variables for your projects:

# List all environment variables for the current project
crunchycone-cli env list

# Get a specific environment variable
crunchycone-cli env get DATABASE_URL

# Set an environment variable
crunchycone-cli env set DATABASE_URL "postgres://user:pass@host:5432/db"

# Set environment variable by reading value from local .env file
crunchycone-cli env set DATABASE_URL --from-env LOCAL_DATABASE_URL

# Remove an environment variable
crunchycone-cli env unset DATABASE_URL

# Override API URL
crunchycone-cli env list --api-url https://api.crunchycone.com

# Specify project ID (auto-detected from crunchycone.toml if not provided)
crunchycone-cli env list --project-id <project-id>

# JSON output for scripting
crunchycone-cli env list --json
crunchycone-cli env get DATABASE_URL --json
crunchycone-cli env set DATABASE_URL "value" --json

Secrets Management

Manage encrypted secrets for your projects (write-only for security):

# List all secret names (values are always masked)
crunchycone-cli secrets list

# Set a secret
crunchycone-cli secrets set JWT_SECRET "your-secret-value"

# Set secret by reading value from local .env file
crunchycone-cli secrets set JWT_SECRET --from-env LOCAL_JWT_SECRET

# Set multiple secrets at once
crunchycone-cli secrets set-batch JWT_SECRET=secret1 API_KEY=secret2

# Delete a secret
crunchycone-cli secrets delete JWT_SECRET

# Skip confirmation prompt
crunchycone-cli secrets delete JWT_SECRET --confirm

# JSON output for scripting
crunchycone-cli secrets list --json
crunchycone-cli secrets set JWT_SECRET "value" --json
crunchycone-cli secrets set-batch KEY1=val1 KEY2=val2 --json
crunchycone-cli secrets delete JWT_SECRET --json --confirm

Important Notes:

• All env and secrets commands work with the platform by default
• Use --from-env flag to read values from your local .env file
• Secrets are write-only - you cannot retrieve secret values for security
• Commands automatically use the correct environment (dev/prod) from your crunchycone.toml
• Use --json flag for structured output suitable for scripting and automation
• JSON mode suppresses interactive prompts and provides machine-readable responses

Database Management

Manage SQLite databases for your projects with Turso integration:

# Upload SQLite database to your project
crunchycone-cli database upload ./app.db

# Upload with override (create new version if database exists)
crunchycone-cli database upload ./app.db --override

# Upload from a directory containing database files
crunchycone-cli database upload ./database-folder

# Download current database
crunchycone-cli database download

# Download and extract to specific directory
crunchycone-cli database download --extract ./backup

# Download to specific file
crunchycone-cli database download ./my-backup.tar.gz

# Check database status and version history
crunchycone-cli database status

# Use short alias 'db' instead of 'database'
crunchycone-cli db upload ./app.db
crunchycone-cli db download --extract ./backup
crunchycone-cli db status

# Verbose mode for debugging API requests
crunchycone-cli database upload ./app.db --verbose

# JSON output for scripting
crunchycone-cli database status --json
crunchycone-cli database upload ./app.db --json

Database Features:

• Automatic Detection: Detects SQLite files (.db, .sqlite, .sqlite3) and companion files (WAL, SHM)
• File Validation: Validates SQLite file integrity before upload
• Compression: Automatically compresses databases using tar.gz format
• Versioning: Maintains database history with automatic cleanup (30 days)
• Size Limits: Supports databases up to 20GB
• Turso Integration: Seamless integration with Turso for scalable SQLite hosting
• Multi-file Support: Handles main database file plus WAL and SHM files

Coming Soon

• SSH key management
• Advanced deployment commands
• Team collaboration features

License

MIT