Buddy CLI

Buddy is the official command-line interface for the Stacks framework. It provides a comprehensive set of commands to help you develop, build, test, and deploy your Stacks applications with ease.

Overview

The Buddy CLI is designed with developer experience in mind, following the "convention over configuration" philosophy. It provides sensible defaults while remaining highly configurable for advanced use cases.

Installation

Buddy comes pre-installed with every Stacks project. When you create a new Stacks project, Buddy is automatically available:

# Create a new Stacks project
panx @stacksjs/buddy new my-project

# Navigate to your project
cd my-project

# Buddy is now available
buddy --help

Pantry Execution

Run Buddy without a project through Pantry's isolated package executor:

panx @stacksjs/buddy --help

This invocation uses Pantry's versioned package-manager and registry boundaries. See the pinned package-manager and registry contracts; Buddy does not replace their resolution or integrity rules.

Configuration

Buddy automatically reads configuration from your project's config files. Most commands work out of the box without any additional setup.

Project Configuration

Buddy respects your project's configuration files located in the config/ directory:

• config/app.ts - Application settings
• config/database.ts - Database configuration
• config/cloud.ts - Cloud deployment settings
• config/dns.ts - DNS configuration

CLI Aliases

The published @stacksjs/buddy package ships buddy, bud, and stx bins, so any command can be run under any of the three names. Inside this repository the CLI is invoked as ./buddy:

./buddy fresh   # inside this repo
buddy fresh     # via the published package (bud and stx work too)

Command Structure

Buddy commands follow a consistent structure:

buddy <command> [subcommand] [arguments] [options]

Common Options

Most commands support these common options:

Getting Help

To see all available commands:

buddy --help

To get help for a specific command:

buddy <command> --help

Quick Reference

Here are some of the most commonly used commands:

# Development
buddy dev              # Start development server
buddy dev:api          # Start API development server
buddy dev:docs         # Start documentation server

# Building
buddy build            # Build for production
buddy build:components # Build component library

# Database
buddy migrate          # Run database migrations
buddy seed             # Seed database with data

# Testing
buddy test             # Run test suite
buddy lint             # Run linter

# Deployment
buddy deploy           # Deploy to cloud
buddy cloud:remove     # Remove cloud infrastructure

Troubleshooting

Command Not Found

If you encounter a "command not found" error:

1. Ensure you're in a Stacks project directory
2. Run buddy install to install dependencies
3. Check that Bun is properly installed

Permission Issues

Some commands may require elevated permissions:

sudo buddy upgrade:binary  # Upgrade the Buddy binary

Verbose Mode

Enable verbose mode to see detailed output for debugging:

buddy <command> --verbose

Learn More

Explore the individual command documentation for detailed information:

• Development Server - Start dev servers
• Build Commands - Build for production
• Database Commands - Manage database
• Testing Commands - Run tests
• Deployment - Deploy applications