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
- app/Commands.ts — name → file mapping
- Event listeners — CLI events in
app/Listeners/Console.ts - 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 instorage/framework/core/buddy/src/commands/ - Commands are auto-discovered from
app/Commands.tsregistry - 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
