stacks-cli

name	stacks-cli
description	Use when building CLI commands or tools with Stacks — the @stacksjs/cli package for creating commands with argument parsing, option handling, colored output, tables, progress indicators, prompts, or integrating with the buddy command system. Covers @stacksjs/cli and app/Commands/.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

Stacks CLI Framework

The @stacksjs/cli package provides the foundation for building CLI commands, used internally by the buddy CLI.

Key Paths

• Core package: storage/framework/core/cli/src/
• CLI configuration: config/cli.ts
• Application commands: app/Commands/
• Command registry: app/Commands.ts

Creating Commands

Simple Command

// app/Commands/Greet.ts
export default {
  name: 'greet',
  description: 'Greet a user',
  alias: 'g',
  options: {
    name: { alias: 'n', description: 'Name to greet', default: 'World' },
    loud: { alias: 'l', description: 'Shout the greeting', type: 'boolean' }
  },
  handle: async ({ options }) => {
    const greeting = `Hello, ${options.name}!`
    console.log(options.loud ? greeting.toUpperCase() : greeting)
  }
}

Register in app/Commands.ts

export default {
  'greet': 'Greet',
  'inspire': 'Inspire',
}

Three Registration Methods

1. app/Commands.ts — name → file mapping
2. Event listeners — CLI events in app/Listeners/Console.ts
3. Inline — direct command definitions

CLI Event Listeners

// app/Listeners/Console.ts
export default function(cli: CLI) {
  cli.on('custom:command', () => {
    console.log('Custom command executed!')
  })

  cli.on('my:*', () => {
    // Wildcard — matches my:anything
  })

  cli.on('unknown:!', () => {
    // Default/fallback handler
  })
}

Output Formatting

Via @stacksjs/utils color functions (available in CLI context):

import { bold, green, red, yellow, dim, underline } from '@stacksjs/utils'

console.log(green('✓ Success'))
console.log(red('✗ Error'))
console.log(yellow('⚠ Warning'))
console.log(bold('Important'))
console.log(dim('Subtle info'))

config/cli.ts (BinaryConfig)

{
  name: 'My Custom CLI',
  command: 'mycli',
  description: 'My custom CLI tool',
  deploy: true
}

CLI Commands

• buddy make:command [name] — scaffold a new command

Compiled Binaries

buddy build:cli                    # build CLI binary
# Compiles for: linux-x64, linux-arm64, windows-x64, darwin-x64, darwin-arm64

Gotchas

• Application commands go in app/Commands/, framework commands in storage/framework/core/buddy/src/commands/
• Commands are auto-discovered from app/Commands.ts registry
• CLI events support wildcards (*) and default handlers (!)
• The buddy CLI lazy-loads commands — not all load at startup
• Output formatting uses ANSI colors from @stacksjs/utils
• Custom CLIs can be compiled to platform-specific binaries
• The CLI framework is separate from buddy — buddy uses it internally