Skills Guide

Stacks Buddy CLI

VerifiedCaution

CLI runtime for the Stacks framework with 50+ lazy-loaded commands for development, deployment, and scaffolding.

Download and use
Sby Skills Guide Bot
DevelopmentIntermediate
7/26/2026
Claude CodeCursorCodex
#stacks-framework#cli#scaffolding#lazy-loading#typescript

Recommended for

Backend developerClaude CodeCode reviewFrontend developerCursorFullstack developer

Automated summary

Describes the architecture of the Stacks framework's Buddy CLI: its lazy-loaded command registry, startup flow, buddy.config.ts file and plugin system.

Strengths

  • Maps the exact file paths (buddy, lazy-commands.ts, app/Commands.ts) needed to work on the CLI.
  • Explains lazy loading and command groups, which helps add a command without slowing cold starts.
  • Documents buddy.config.ts (theme, aliases, plugins) with an explicit TypeScript interface.
  • Lists the commands that bypass the APP_KEY check, useful when troubleshooting.

Limitations

  • The content cuts off mid-way through the BuddyPlugin interface, so the hooks section is incomplete.
  • The description promises flags and options for all 50+ commands, but no individual command is actually detailed.
  • Tightly bound to the Stacks framework and Bun >= 1.3.0, so hardly reusable elsewhere.
When to use it

Use it when working inside a Stacks project and you need to understand, extend or debug the buddy CLI.

When not to use it

Avoid it for non-Stacks projects or for learning how to build a generic TypeScript CLI.

Security analysis

Caution
Quality score78/100

This is a reference/documentation skill for the Stacks Buddy CLI. It never instructs the agent to execute anything destructive or to exfiltrate data, and there is no obfuscated payload or prompt-injection attempt. However, it declares Bash and documents a large surface of powerful operations (dropping all tables, destroying cloud stacks with elevated IAM, decrypting/printing env secrets, sudo upgrades, hosts-file edits), so an agent acting on it could cause real damage or leak credentials if it ran commands without confirmation. That warrants caution rather than a clean 'safe' rating.

Findings
  • •Documents destructive CLI operations without safety framing: `migrate:fresh` (drops all tables), `cloud:remove`/`cloud:destroy` (tears down cloud infrastructure and reportedly creates temporary IAM roles with AdministratorAccess), and `process.kill(0, 'SIGKILL')` child-process cleanup.
  • •Documents commands that read and manipulate credentials/secrets: `env:get`/`env:decrypt` output (json/shell/eval/stdout), `keypair`/`rotate`, and `mail:*` commands loading AWS credentials from `.env.production` and `~/.aws/credentials`. A careless agent could surface secret values in logs.
  • •Declares Bash/Write/Edit tools and references sudo-requiring operations (`upgrade:binary` requires sudo) and host-file modification (`setup:ssl` edits hosts file, trusts certs, writes to `~/.stacks/ssl/`).
  • •No obfuscation, no curl|sh installers, no outbound data transfer, no instruction to disable safety — the content is descriptive reference material, not an execution recipe.
  • •Documents destructive operations without any warning or confirmation guidance: `migrate:fresh` (drops all tables), `buddy clean`, `cloud:remove`/`undeploy` with `--force --yes`, and `cloud:cleanup` (removes S3 buckets, Lambda functions, VPCs, CloudWatch logs, Parameter Store, IAM users). An agent with Bash access could plausibly run these from a casual user request with irreversible, high-blast-radius results.
  • •Notes that `cloud:remove` handles stuck stacks by creating temporary IAM roles with AdministratorAccess — describes privileged, security-sensitive behavior without flagging the risk.
  • •Secret-handling paths are documented without caution: `env:decrypt -o/--stdout`, `mail:credentials` (SMTP credentials printed), and `mail:user:add --password <password>` (password on the command line/history). No exfiltration is instructed, but these invite accidental secret exposure in logs/transcripts.
  • •No prompt-injection, obfuscation, curl|sh, or data-sending instructions were found; the content is purely CLI reference documentation with legitimate tool use (Read/Edit/Write/Bash/Grep/Glob are appropriate for a codebase-aware reference skill).
How this analysis is made

Examples

Add a custom command
Add a new 'db:stats' command under app/Commands/ for the Stacks buddy CLI, register it in app/Commands.ts, and make sure it loads lazily like the built-in commands.
Understand lazy loading
Explain how lazy-commands.ts loads a command in the Stacks buddy CLI, what loadCommandGroup does, and where I'd add a new 'maintenance' command group.
Configure buddy.config.ts
Create a buddy.config.ts for my Stacks project that uses the dracula theme, maps the alias 'r' to release, and registers a local plugin that adds a beforeCommand hook.

name: stacks-buddy description: Use when working with the Stacks CLI (buddy/bud/stacks/stx) — understanding all 50+ commands with their flags and options, adding custom commands, the make:* scaffolding commands, development server commands, build commands, deployment commands, email/mail commands, environment management, or domain/DNS commands. Covers @stacksjs/buddy and all CLI command files. license: MIT compatibility: Bun >= 1.3.0, TypeScript allowed-tools: Read Edit Write Bash Grep Glob

Stacks Buddy CLI

The complete CLI runtime for the Stacks framework with 50+ commands, lazy-loaded for fast cold starts.

Key Paths

  • Core package: storage/framework/core/buddy/src/
  • CLI entry point: storage/framework/core/buddy/src/cli.ts
  • Commands directory: storage/framework/core/buddy/src/commands/
  • Lazy command registry: storage/framework/core/buddy/src/lazy-commands.ts
  • Config system: storage/framework/core/buddy/src/config.ts
  • Shell entry: buddy (shell script at project root that invokes bun run ./storage/framework/core/buddy/src/cli.ts)
  • Application commands: app/Commands/
  • Command registry: app/Commands.ts
  • Make templates: storage/framework/defaults/

CLI Aliases

All invoke the same CLI: ./buddy, bud, stacks, stx

Architecture

Lazy Loading System

Commands are lazy-loaded for performance. The lazy-commands.ts file maps command names to their file paths and export names. When a command is invoked, only that command's module is loaded.

// lazy-commands.ts registry structure
const commandRegistry: Record<string, CommandLoader> = {
  'about': { path: './commands/about.ts', exportName: 'about' },
  'build': { path: './commands/build.ts', exportName: 'build' },
  // ... 40+ more entries
}

Key functions:

  • loadCommand(name, buddy) - Load a single command lazily
  • loadCommands(names, buddy) - Load multiple commands with 5-second timeout per command
  • loadCommandGroup(groupName, buddy) - Load related commands ('development', 'database', 'scaffolding', 'deployment', 'info')
  • loadAllCommands(buddy) - Load all commands (for interactive mode or list command)
  • getCommandsToLoad(args) - Determine which commands to load based on CLI arguments
  • getCommandNames() - Get all command names without loading them (for autocomplete)

Command groups defined in lazy-commands.ts:

  • minimal: version, help
  • development: dev, build, test, lint
  • database: migrate, seed, fresh
  • scaffolding: make, generate
  • deployment: deploy, release, cloud
  • info: about, doctor, list

Startup Flow (cli.ts)

  1. Parse args to determine requested command
  2. Skip expensive setup for minimal commands (--version, --help, help, version)
  3. For full commands: load setup + key commands, check APP_KEY, load lazy commands, load user commands from app/Commands/
  4. For no arguments with interactive TTY: show interactive menu with select prompt
  5. Parse and execute

Commands that skip APP_KEY check

build, lint, lint:fix, test, test:types, test:unit, test:feature, typecheck, types:fix, types:generate, clean, fresh, about, doctor, setup, setup:ssl, setup:oh-my-zsh, deploy

buddy.config.ts Support

Optional config file at project root. Validated with validateConfig(). Supports:

interface BuddyConfig {
  theme?: 'default' | 'dracula' | 'nord' | 'solarized' | 'monokai'
  emoji?: boolean
  commands?: Array<(cli: CLI) => void>
  defaultFlags?: { verbose?: boolean, quiet?: boolean, debug?: boolean }
  aliases?: Record<string, string>  // e.g. { 'r': 'release' }
  plugins?: Array<BuddyPlugin | string>
}

Config files searched in order: buddy.config.ts, buddy.config.js, .buddy.config.ts, .buddy.config.js

Plugin System

Plugins can register commands, add hooks (beforeCommand/afterCommand):

interface BuddyPlugin {
  name: string
  version?: string
  setup: (cli: CLI) => void | Promise<void>
  hooks?: {
    beforeCommand?: (context: any) => void | Promise<void>
    afterCommand?: (context: any) => void | Promise<void>
  }
}

Interactive Mode

When buddy is invoked with no arguments on an interactive TTY, it shows a select menu:

  • Start development server
  • Build for production
  • Run tests
  • List all commands
  • Run health checks
  • Show system information
  • Show help
  • Exit

Development Commands

buddy dev [server] - Start development server(s)

buddy dev                    # start ALL dev servers (frontend, API, docs, dashboard) + reverse proxy
buddy dev frontend           # frontend only (positional arg)
buddy dev api                # API only
buddy dev docs               # documentation only
buddy dev dashboard          # dashboard only
buddy dev desktop            # desktop only
buddy dev system-tray        # system tray only
buddy dev -f/--frontend      # frontend only (flag)
buddy dev -a/--api           # API only
buddy dev -c/--components    # components dev server
buddy dev -d/--dashboard     # dashboard only
buddy dev -k/--desktop       # desktop only
buddy dev -o/--docs          # docs only
buddy dev -s/--system-tray   # system tray only
buddy dev -i/--interactive   # interactive server selection menu
buddy dev -l/--with-localhost # include localhost URL in output
buddy dev -p/--project [name]
buddy dev --verbose

Sub-commands with aliases:

buddy dev:components         # component library dev server
buddy dev:docs               # documentation dev server
buddy dev:desktop            # desktop app dev server
buddy dev:api                # API dev server
buddy dev:frontend           # frontend dev server (aliases: dev:pages, dev:views)
buddy dev:dashboard          # dashboard dev server (alias: dev:admin)
buddy dev:system-tray        # system tray dev server (alias: dev:tray)

When running buddy dev with no flags (all servers), it:

  1. Prints Vite-style output showing all server URLs
  2. Sets STACKS_PROXY_MANAGED=1 env var
  3. Starts frontend, API, docs, dashboard servers in parallel
  4. If APP_URL has a custom domain, starts reverse proxy (rpx) for HTTPS with subdomains
  5. Uses environment variables: PORT (default 3000), PORT_API (3008), PORT_DOCS (3006), PORT_ADMIN (3002)
  6. Cleans up child processes on SIGINT/SIGTERM via process.kill(0, 'SIGKILL')

Reverse proxy (rpx):

  • Proxies localhost:PORT -> domain, localhost:PORT_API -> api.domain, etc.
  • SSL certs stored at ~/.stacks/ssl/
  • Only starts when APP_URL is set to a custom domain (not localhost)

Build Commands

buddy build [type] - Build for production

buddy build                  # defaults to building stacks framework
buddy build components       # positional: component library
buddy build vue              # Vue components
buddy build web-components   # web components
buddy build functions        # function library
buddy build views            # frontend views
buddy build docs             # documentation
buddy build buddy            # CLI binary
buddy build cli              # CLI binary (alias for buddy)
buddy build stacks           # framework
buddy build server           # Docker image

Flags:

buddy build -c/--components        # component library (Vue + Web Components)
buddy build -w/--web-components    # web component library only
buddy build -f/--functions         # function library
buddy build -p/--views/--pages     # frontend views
buddy build -d/--docs              # documentation site
buddy build -b/--buddy             # CLI binary
buddy build -s/--stacks            # framework core
buddy build --server               # Docker image

Sub-commands with aliases:

buddy build:components       # component libraries (alias: prod:components)
buddy build:cli              # CLI binary (alias: prod:cli)
buddy build:server           # Docker image (aliases: prod:server, build:docker)
buddy build:functions        # function library
buddy build:web-components   # web components (aliases: build:wc, prod:web-components, prod:wc)
buddy build:docs             # documentation (aliases: prod:docs, build:documentation, prod:documentation)
buddy build:core             # Stacks core packages
buddy build:desktop          # desktop application (alias: prod:desktop)
buddy build:stacks           # Stacks framework

Database Commands

buddy migrate - Run database migrations

buddy migrate                # run pending migrations (alias: db:migrate)
buddy migrate -d/--diff      # show SQL that would be run without executing
buddy migrate -a/--auth      # also migrate auth tables (oauth_clients, oauth_access_tokens, etc.)
buddy migrate --verbose

buddy migrate:fresh          # drop all tables and re-migrate (alias: db:fresh)
buddy migrate:fresh -s/--seed   # seed after fresh migration
buddy migrate:fresh -a/--auth   # include auth tables
buddy migrate:fresh -d/--diff   # show SQL without running

buddy migrate:dns            # DNS migration for APP_URL domain

Both migrate and migrate:fresh validate that models exist in app/Models or storage/framework/defaults/models before running.

buddy seed - Seed database

buddy seed                   # seed database (alias: db:seed)
buddy seed --verbose

Code Generation (make:*)

buddy make [type] - Scaffolding commands

All make commands accept -n/--name [name] and --verbose flags.

buddy make:action [name]      # create action in app/Actions/
buddy make:certificate        # generate SSL certificate (alias: make:cert)
buddy make:command [name]     # create CLI command in app/Commands/
  --signature [sig]           # CLI command name
  --description [desc]        # command description
  --no-register               # skip registering in Commands.ts
buddy make:component [name]   # create STX component
buddy make:database [name]    # create database
buddy make:factory [name]     # create model factory (stub)
buddy make:function [name]    # create composable function
buddy make:job [name]         # create background job
  -q/--queue [queue]          # queue name (default: 'default')
  -c/--class                  # class-based job
  -t/--tries [n]              # retry attempts (default: 3)
  -b/--backoff [n]            # backoff delay in seconds (default: 3)
buddy make:lang [name]        # create i18n language file
buddy make:migration [name]   # create database migration
buddy make:model [name]       # create data model
buddy make:notification [name]# create notification
  -e/--email                  # email notification (default: true)
  -c/--chat                   # chat notification
  -s/--sms                    # SMS notification
buddy make:policy [name]      # create authorization policy
  -m/--model [model]          # associated model
  --no-register               # skip registering in Gates.ts
buddy make:resource [name]    # create API resource
  -m/--model [model]          # associated model
  -c/--collection             # create collection resource
buddy make:queue-table        # create queue migration
buddy make:stack [name]       # create full stack
buddy make:view [name]        # create page/view (alias: make:page)

Code Generation (generate)

buddy generate - Generate artifacts

buddy generate                     # all artifacts (if no flags, runs invoke)
buddy generate -t/--types          # TypeScript types
buddy generate -e/--entries        # library entry points
buddy generate -w/--web-types      # web-types.json for IDEs
buddy generate -c/--custom-data    # VS Code custom data
buddy generate -i/--ide-helpers    # IDE helpers
buddy generate -c/--component-meta # component meta information
buddy generate -p/--pantry         # pantry config
buddy generate -o/--openapi        # OpenAPI specification
buddy generate --core-symlink      # core framework symlink

buddy generate:types               # TypeScript types (alias: types:generate)
buddy generate:entries             # library entry points
buddy generate:web-types           # web-types.json
buddy generate:vscode-custom-data  # VS Code custom data
buddy generate:ide-helpers         # IDE helpers
buddy generate:component-meta      # component meta
buddy generate:pantry-config       # pantry config
buddy generate:openapi-spec        # OpenAPI spec (alias: generate:openapi)
buddy generate:migrations          # migration diffs from models (stub)
buddy generate:core-symlink        # core symlink for core developers

Environment Management

buddy env:* - Manage environment variables

buddy env:get [key]              # get specific env var
  -f/--file [file]               # env file path (default: .env)
  --format [json|shell|eval]     # output format (default: json)
  -a/--all                       # get all env vars
  -p/--pretty                    # pretty print
buddy env:set [key] [value]      # set env var
  -f/--file [file]               # env file path
  -fk/--file-keys [path]         # keys file path
  --plain                        # don't encrypt the value
buddy env:encrypt [key]          # encrypt env var(s)
  -f/--file [file]               # env file path
  -fk/--file-keys [path]         # keys file path
  -o/--stdout                    # output to stdout
  -ek/--exclude-key [key]        # key to exclude from encryption
buddy env:decrypt [key]          # decrypt env var(s)
  -f/--file [file]               # env file path
  -fk/--file-keys [path]         # keys file path
  -o/--stdout                    # output to stdout
buddy env:keypair [key]          # generate encryption keypair
  -f/--file [file]               # env file path
  --format [json|shell]          # output format (default: json)
buddy env:rotate [key]           # rotate encryption keys
  -f/--file [file]               # env file path
  -ek/--exclude-key [key]        # key to exclude
  -o/--stdout                    # output to stdout
buddy env:check                  # validate environment configuration
  -f/--file [file]               # env file path

env:check validates: .env file exists, variable count, APP_KEY presence, encryption keys (DOTENV_PUBLIC_KEY/DOTENV_PRIVATE_KEY), .env.keys file.

Cloud & Deployment

buddy deploy - Deploy to cloud

Handles full deployment workflow: prerequisites check, pantry install, env setup, APP_KEY, AWS credentials (from .env.{env} or ~/.aws/credentials), domain setup, email DNS records (DKIM, MX, SPF, DMARC), mail user creation.

buddy cloud - Cloud management

buddy cloud --ssh              # SSH into cloud via SSM (alias: --connect)
buddy cloud --diff             # show infrastructure changes (local vs deployed CloudFormation template)
buddy cloud --invalidate-cache # invalidate CloudFront CDN cache
  --paths [paths]              # specific paths to invalidate (default: /*)

buddy cloud:add --jump-box     # add jump box EC2 instance
buddy cloud:remove             # remove cloud infrastructure (aliases: cloud:destroy, cloud:rm, undeploy)
  --jump-box                   # remove just the jump-box
  --force                      # force deletion
  --yes                        # skip confirmation
buddy cloud:optimize-cost      # remove optional resources (jump-box)
buddy cloud:cleanup            # clean up retained resources after stack deletion
  # Cleans: jump-boxes, S3 buckets, Lambda functions, CloudWatch logs,
  # Parameter Store, VPCs, Subnets, CDK remnants, IAM users
buddy cloud:invalidate-cache   # invalidate CloudFront cache
  --paths [paths]              # paths to invalidate
buddy cloud:diff               # show deployed vs local template diff

cloud:remove uses undeployStack() from storage/framework/core/actions/deploy and handles stuck stacks by creating temporary IAM roles.

Domain & DNS

buddy domains:* - Domain management

buddy domains:purchase <domain>     # purchase via Route 53
  --years <n>                       # registration years (default: 1)
  --privacy                         # privacy protection (default: true)
  --auto-renew                      # auto-renew (default: true)
  --first-name/--last-name/etc.     # registrant contact (reads from config.dns.contactInfo)
  --admin-*/--tech-*                # admin/tech contact overrides
  --privacy-admin/--privacy-tech/--privacy-registrant
  --contact-type <type>             # default: 'person'
buddy domains:add <domain>          # add domain you own to cloud
buddy domains:remove <domain>       # remove domain from cloud
  --yes                             # skip confirmation

buddy dns [domain] - DNS query tool (uses @stacksjs/dnsx)

buddy dns [domain]                  # query DNS (defaults to APP_URL)
buddy dns -q/--query <query>        # host to query
buddy dns -t/--type <type>          # record type: A, MX, NS, etc. (default: A)
buddy dns -n/--nameserver <ns>      # custom nameserver
buddy dns --class <class>           # network class: IN, CH, HS
buddy dns -U/--udp                  # DNS over UDP
buddy dns -T/--tcp                  # DNS over TCP
buddy dns -S/--tls                  # DNS over TLS
buddy dns -H/--https               # DNS over HTTPS
buddy dns -1/--short                # short mode
buddy dns -J/--json                 # JSON output

Email / Mail Commands

buddy email:* - Email management (SES/S3 based)

buddy email                  # list available email commands
buddy email:verify           # check SES domain verification, show DKIM records
buddy email:test [recipient] # send test email via SES
buddy email:list             # list configured mailboxes from config/email.ts
buddy email:logs             # view CloudWatch email processing logs
  -n/--lines <count>         # number of log lines (default: 20)
buddy email:status           # show email server deployment status via CloudFormation
buddy email:inbox [mailbox]  # view inbox emails from S3 bucket
  -n/--limit <count>         # number of emails (default: 20)
  --raw <id>                 # show raw .eml content
  --bucket <name>            # S3 bucket override
buddy email:reprocess        # reprocess raw emails from S3 into mailbox structure
  --bucket <name>            # S3 bucket override
  --prefix <prefix>          # S3 prefix (default: inbox/)
  --domain <domain>          # email domain (default: stacksjs.com)

Email inbox reads from S3 in two strategies:

  1. mailboxes/{domain}/{user}/inbox.json (processed inbox)
  2. Falls back to raw emails in inbox/ or incoming/ prefixes

buddy mail:* - Mail server management

buddy mail:user:add <email>       # add mail user to DynamoDB
  --password <password>           # user password (auto-generated if not provided)
buddy mail:user:list              # list all mail users from DynamoDB
buddy mail:user:delete <email>    # delete mail user
buddy mail:proxy                  # start local IMAP proxy for Mail.app
  --port <port>                   # IMAP proxy port (default: 1993)
  --api <url>                     # mail API URL (auto-detected from CloudFormation)
buddy mail:test                   # test mail API connection
buddy mail:credentials [email]    # show SMTP credentials
buddy mail:logs                   # show mail server logs from EC2 via SSM
  -n/--lines <count>              # number of lines (default: 50)
  -f/--follow                     # follow log output (poll every 5s)
  --filter <pattern>              # filter by pattern (AUTH, LOGIN, error, etc.)
buddy mail:status                 # show mail server service/ports/memory via SSM
buddy mail:port25:request         # request port 25 unblock
  --provider <aws|hetzner>        # cloud provider (default: aws)
  --instance-id <id>              # EC2 instance ID (auto-detected)
  --elastic-ip <ip>               # Elastic IP
  --rdns <hostname>               # reverse DNS hostname
  --use-case <text>               # use case description
buddy mail:port25:status          # check outbound port 25 status
  --provider <aws|hetzner>        # cloud provider (default: aws)
buddy mail:server                 # start SMTP relay server
  --port <port>                   # SMTP port (default: 587)

Code Quality

buddy lint - Lint codebase (uses pickier)

buddy lint                   # lint project (runs pickier in lint mode)
buddy lint -f/--fix          # auto-fix lint errors
buddy lint:fix               # auto-fix (standalone command)
buddy format                 # format code
  -w/--write                 # write changes (default when no flags)
  -c/--check                 # check formatting only
buddy format:check           # check formatting without changes

Internal implementation: runs bunx --bun pickier run --mode lint --config ./pickier.config.ts (with --fix when requested).

buddy test - Run test suite

buddy test                   # run all tests
buddy test -f/--feature      # feature tests only
buddy test -u/--unit         # unit tests only
buddy test:unit              # unit tests (standalone)
buddy test:feature           # feature tests (standalone)
buddy test:ui                # tests in browser
buddy test:types             # typecheck (alias: typecheck)

Project Management

buddy fresh                  # reinstall dependencies
buddy install                # install deps
buddy clean                  # remove node_modules
buddy outdated               # check outdated deps
buddy add                    # add dependency

buddy upgrade                # upgrade Stacks framework (alias: update)
  -v/--version <version>     # install specific version (e.g., 0.70.23)
  --canary                   # upgrade to canary build
  --stable                   # switch to stable release
  -f/--force                 # force re-download
buddy upgrade:all            # upgrade framework + dependencies + Bun + binary
buddy upgrade:dependencies   # upgrade dependencies (alias: upgrade:deps)
buddy upgrade:bun            # upgrade Bun runtime
buddy upgrade:shell          # upgrade shell integration (Oh My Zsh)
buddy upgrade:binary         # upgrade stacks binary (requires sudo)

Maintenance Mode

buddy down                   # put app in maintenance mode
  --message [msg]            # maintenance message
  --retry [seconds]          # retry-after header value
  --secret [token]           # bypass token (access via: your-app.com/{token})
  --allow [ip...]            # allowed IP addresses
  --redirect [url]           # redirect all requests
  --status [code]            # HTTP status code (default: 503)
buddy up                     # bring app out of maintenance mode
buddy status                 # check maintenance status (alias: maintenance:status)

Uses @stacksjs/server module's down(), up(), isDownForMaintenance(), maintenancePayload() functions.

Other Commands

buddy about                  # display Stacks version, Bun/Node versions, OS, environment
buddy doctor                 # health checks (Bun version, Node, package.json, .env, APP_KEY)
buddy tinker                 # interactive REPL with Stacks preloaded
  -e/--eval [expr]           # evaluate expression and exit
  --print [expr]             # evaluate, print, and exit
  --no-banner                # skip welcome banner
  --preload [modules]        # comma-separated modules to preload
buddy key:generate           # generate and set APP_KEY
buddy commit                 # conventional commit helper (uses runCommit from @stacksjs/actions)
buddy changelog              # generate CHANGELOG.md
  -q/--quiet                 # minimal output
  -d/--dry-run               # preview without writing
buddy release                # release new version via GitHub Actions
  --dry-run                  # preview without releasing
buddy route                  # route management
buddy share [type]           # share local dev server via public tunnel (localtunnel)
  -p/--port <port>           # local port
  --server <url>             # tunnel server (default: api.localtunnel.dev)
  --subdomain <name>         # request specific subdomain
  # Supports: frontend, api, backend, admin, dashboard, desktop, docs
  # Auto-starts companion services (API, docs) for frontend shares
buddy search                 # search engine operations
buddy configure              # configure project
buddy create                 # create new project
buddy completion [shell]     # shell completion (bash/zsh/fish)
buddy ports                  # port management
  -l/--list                  # list used ports (default)
  -c/--check                 # check port availability
buddy ports:list             # list ports for project
buddy ports:check            # check ports across all Stacks projects
buddy setup                  # ensure project is set up correctly (alias: ensure)
  --skip-aws                 # skip AWS configuration
  --skip-keygen              # skip APP_KEY generation
buddy setup:ssl              # setup SSL certs + hosts file (alias: ssl:setup)
  -d/--domain [domain]       # custom domain (defaults to APP_URL)
  --skip-hosts               # skip hosts file modification
  --skip-trust               # skip certificate trust
buddy setup:oh-my-zsh        # enable Oh My Zsh integration
buddy telemetry              # telemetry management
buddy list                   # list all available commands
buddy version                # display version (flags: --version, -v)
buddy saas                   # SaaS management
buddy sms                    # SMS commands
buddy phone                  # phone commands
buddy http                   # HTTP commands
buddy auth                   # auth commands
buddy queue                  # queue management
buddy schedule               # schedule management
buddy package                # package management
buddy projects               # project management
buddy prepublish             # pre-publish checks
buddy stacks                 # Stacks framework commands (registered as 'stack' in lazy-commands)

Adding Custom Commands

Method 1: Commands.ts Registry (preferred)

// app/Commands.ts
export default {
  'inspire': 'Inspire',                              // simple: maps to app/Commands/Inspire.ts
  'deploy-hooks': { file: 'DeployHooks', enabled: true, aliases: ['dh'] },  // with options
  'disabled-cmd': { file: 'Disabled', enabled: false }, // disabled command
}

// app/Commands/Inspire.ts
import type { CLI } from '@stacksjs/cli'

export default function (buddy: CLI) {
  buddy
    .command('inspire', 'Display inspirational quote')
    .option('-t, --two', 'Show two quotes')
    .action(async (options: { two?: boolean }) => {
      console.log(randomQuote())
      if (options.two) console.log(randomQuote())
    })
}

Method 2: Auto-discovery (fallback)

If app/Commands.ts does not exist, all .ts files in app/Commands/ are auto-discovered and loaded. Each must export a default function that receives the CLI instance.

Method 3: buddy.config.ts

// buddy.config.ts
export default {
  commands: [
    (cli) => {
      cli.command('custom', 'My custom command').action(() => console.log('Hello'))
    },
  ],
  aliases: {
    'r': 'release',
    'dep': 'deploy',
  },
}

Gotchas

  • Application commands go in app/Commands/, framework commands in storage/framework/core/buddy/src/commands/
  • The buddy file at root is a shell script that bootstraps pantry, ensures Bun is available, then runs bun run ./storage/framework/core/buddy/src/cli.ts
  • Commands are lazy-loaded with a 5-second timeout per command to prevent startup hangs
  • The list command loads ALL commands to display them
  • When no command matches, the CLI loads only version for minimal overhead
  • APP_KEY is auto-generated if not set (except for commands in the skipAppKeyCheck list)
  • buddy dev with custom APP_URL starts a reverse proxy (rpx) that handles SSL certificates via ~/.stacks/ssl/
  • dev:frontend has aliases dev:pages and dev:views
  • dev:dashboard has alias dev:admin
  • dev:system-tray has alias dev:tray
  • build with no flags defaults to building the Stacks framework (--stacks)
  • cloud:remove handles stuck CloudFormation stacks by creating temporary IAM roles with AdministratorAccess
  • mail:* commands load AWS credentials from .env.production and ~/.aws/credentials
  • share uses localtunnel and auto-starts companion dev servers (API, docs) for frontend shares
  • Console listeners can be registered via app/Listeners/Console.ts

From the file to a first result

The download contains exactly the content displayed on this page. This copy may differ from the latest version in the source repository.

View the source and supporting files

This download contains SKILL.md only. Any scripts, references, templates and dependencies are not included. Get the required files from the source, preserving their directory structure, before continuing.

1. Download the file

Download SKILL.md

From the root of a test project, save the file as .skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md, or use the command below. This folder is for inspecting the skill before installation.

Command for macOS/Linux or WSL: requires a POSIX shell and curl. On Windows without WSL, use the download button and create the folder manually.

mkdir -p '.skill-downloads/stacks-buddy-cli-ms1aw5zl' && curl --fail --show-error --location 'https://skills-guides.com/api/skills/stacks-buddy-cli-ms1aw5zl/download' --output '.skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md.part' && mv '.skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md.part' '.skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md'

2. Check prerequisites

Read SKILL.md before using it. If it references scripts or external services, inspect them and prepare the required access in your test environment.

Environment declared by the author: Bun >= 1.3.0, TypeScript

Tools declared by the author (check availability in your agent): Read Edit Write Bash Grep Glob

No recognized prerequisites section in this file. This does not mean it is self-contained: libraries, tools and access requirements may be mentioned elsewhere in the content or source repository.

The platforms on this page are catalog indications. The paths below follow tool documentation; they do not prove this skill has been run in those tools. No minimum tool version is confirmed for this listing.

3. Load the skill

After inspection, copy the complete folder into your project using one of the commands below, then open a new tool session. The command stops if a folder with the same name already exists: compare the files before replacing it.

Claude Code
test -f '.skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md' && test -s '.skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md' && mkdir -p '.claude/skills' && test ! -e '.claude/skills/stacks-buddy' && cp -R '.skill-downloads/stacks-buddy-cli-ms1aw5zl' '.claude/skills/stacks-buddy'

Cursor
test -f '.skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md' && test -s '.skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md' && mkdir -p '.cursor/skills' && test ! -e '.cursor/skills/stacks-buddy' && cp -R '.skill-downloads/stacks-buddy-cli-ms1aw5zl' '.cursor/skills/stacks-buddy'

Codex
test -f '.skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md' && test -s '.skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md' && mkdir -p '.agents/skills' && test ! -e '.agents/skills/stacks-buddy' && cp -R '.skill-downloads/stacks-buddy-cli-ms1aw5zl' '.agents/skills/stacks-buddy'

OpenSkills

OpenSkills must already be installed. The local install/read procedure is checked with OpenSkills 1.5.0, which requires Node.js ≥ 20.6.0. Catalog slugs are not resolved automatically.

Official OpenSkills installation
openskills install './.skill-downloads/stacks-buddy-cli-ms1aw5zl'

openskills read 'stacks-buddy-cli-ms1aw5zl'

Reading should display the installed file content and its base directory. It does not run the skill or install its dependencies.

For an agent that reads AGENTS.md, then sync the index. This command changes AGENTS.md: review the diff before using it.

openskills sync

Manual method or another tool: attach SKILL.md to a conversation, or open it in an agent that can read files. Include any required supporting resources. No universal folder is recognized by every tool.

4. Try a first task

Use a short, synthetic input: an API endpoint, a small document or an interface brief. In a new conversation, attach the file or give the agent its path, then adapt this request:

Read .skill-downloads/stacks-buddy-cli-ms1aw5zl/SKILL.md and apply its instructions to this example: [describe a test input]. Identify any missing files, dependencies or access. Produce the result requested by the skill without inventing data or running unreviewed scripts.

Expected result: output matching the skill instructions, or a precise list of missing prerequisites. A read confirmation alone does not validate a first use. If an external resource is unavailable, that path remains untested.

Related skills

React Hook Form Best Practices

Development

Master React Hook Form: avoid anti-patterns, manage subscriptions, and handle reset, dirty state, and controlled inputs correctly.

Claude CodeCursorWindsurf+2intermediateSafe 108,623
Skills Guide Bot

Emotion to Mantine Migration

Development

Migrate Emotion styled-components to Mantine components with style props and CSS modules. Use when converting .styled.tsx files or removing @emotion imports.

Claude CodeCursorWindsurf+1intermediateSafe 48,981
Skills Guide Bot

Scope Creep Detector

Development

Analyzes git diffs against a stated intent to detect scope creep, unrelated files, broad PRs, and oversized changes, then suggests keep, split, or justify actions.

Claude CodeCursorCodexintermediateSafe 135,015
Skills Guide Bot