also looking at this
Deploy: uniform auth session model (main → production)
#7
282 files
+3028
-64856
| @@ -1,743 +0,0 @@ | ||
| 1 | # Build a CLI | |
| 2 | ||
| 3 | This tutorial will guide you through building command-line interfaces (CLIs) with Stacks. You will learn how to create commands, handle options and arguments, display prompts, and format output. | |
| 4 | ||
| 5 | ## Overview | |
| 6 | ||
| 7 | Stacks makes it easy to create powerful CLIs: | |
| 8 | ||
| 9 | - **Automatic Registration** - Commands are auto-discovered | |
| 10 | - **Type-Safe** - Full TypeScript support with excellent IDE integration | |
| 11 | - **Rich Output** - Colorful output, tables, progress bars, and more | |
| 12 | - **Interactive Prompts** - Confirmations, selections, and text input | |
| 13 | - **Distributable** - Ship as a binary or npm package | |
| 14 | ||
| 15 | ## Configuration | |
| 16 | ||
| 17 | Configure your CLI in `config/cli.ts`: | |
| 18 | ||
| 19 | ```typescript | |
| 20 | // config/cli.ts | |
| 21 | import type { BinaryConfig } from '@stacksjs/types' | |
| 22 | ||
| 23 | export default { | |
| 24 | name: 'My Custom CLI', | |
| 25 | command: 'my-cli', // enables `my-cli <command> <options>` | |
| 26 | description: 'A powerful CLI tool for my project', | |
| 27 | deploy: true, // deploys CLI setup endpoint | |
| 28 | } satisfies BinaryConfig | |
| 29 | ``` | |
| 30 | ||
| 31 | ## Creating Commands | |
| 32 | ||
| 33 | Commands live in the `app/Commands/` directory and are automatically registered. | |
| 34 | ||
| 35 | ### Generate a Command | |
| 36 | ||
| 37 | ```bash | |
| 38 | buddy make:command SendEmails | |
| 39 | ``` | |
| 40 | ||
| 41 | ### Basic Command Structure | |
| 42 | ||
| 43 | ```typescript | |
| 44 | // app/Commands/SendEmails.ts | |
| 45 | import type { CLI } from '@stacksjs/types' | |
| 46 | import process from 'node:process' | |
| 47 | import { log } from '@stacksjs/cli' | |
| 48 | import { ExitCode } from '@stacksjs/types' | |
| 49 | ||
| 50 | export default function (cli: CLI) { | |
| 51 | cli | |
| 52 | .command('send-emails', 'Send pending emails to users') | |
| 53 | .action(() => { | |
| 54 | log.info('Sending emails...') | |
| 55 | ||
| 56 | // Your logic here | |
| 57 | ||
| 58 | log.success('Emails sent successfully!') | |
| 59 | process.exit(ExitCode.Success) | |
| 60 | }) | |
| 61 | ||
| 62 | return cli | |
| 63 | } | |
| 64 | ``` | |
| 65 | ||
| 66 | ### Using the Command | |
| 67 | ||
| 68 | ```bash | |
| 69 | # Using Buddy | |
| 70 | buddy send-emails | |
| 71 | ||
| 72 | # Using your custom CLI (after deployment) | |
| 73 | my-cli send-emails | |
| 74 | ``` | |
| 75 | ||
| 76 | ## Options and Arguments | |
| 77 | ||
| 78 | ### Adding Options | |
| 79 | ||
| 80 | Options are flags that modify command behavior: | |
| 81 | ||
| 82 | ```typescript | |
| 83 | // app/Commands/Greet.ts | |
| 84 | import type { CLI } from '@stacksjs/types' | |
| 85 | import process from 'node:process' | |
| 86 | import { log } from '@stacksjs/cli' | |
| 87 | import { ExitCode } from '@stacksjs/types' | |
| 88 | ||
| 89 | interface GreetOptions { | |
| 90 | name: string | |
| 91 | uppercase: boolean | |
| 92 | times: number | |
| 93 | } | |
| 94 | ||
| 95 | export default function (cli: CLI) { | |
| 96 | cli | |
| 97 | .command('greet', 'Greet someone') | |
| 98 | .option('--name, -n <name>', 'Name to greet', { default: 'World' }) | |
| 99 | .option('--uppercase, -u', 'Output in uppercase', { default: false }) | |
| 100 | .option('--times, -t <count>', 'Number of times to greet', { default: 1 }) | |
| 101 | .action((options: GreetOptions) => { | |
| 102 | let message = `Hello, ${options.name}!` | |
| 103 | ||
| 104 | if (options.uppercase) { | |
| 105 | message = message.toUpperCase() | |
| 106 | } | |
| 107 | ||
| 108 | for (let i = 0; i < options.times; i++) { | |
| 109 | log.info(message) | |
| 110 | } | |
| 111 | ||
| 112 | process.exit(ExitCode.Success) | |
| 113 | }) | |
| 114 | ||
| 115 | return cli | |
| 116 | } | |
| 117 | ``` | |
| 118 | ||
| 119 | Usage: | |
| 120 | ||
| 121 | ```bash | |
| 122 | buddy greet # Hello, World! | |
| 123 | buddy greet --name Alice # Hello, Alice! | |
| 124 | buddy greet -n Alice -u # HELLO, ALICE! | |
| 125 | buddy greet --name Bob --times 3 # Prints 3 times | |
| 126 | ``` | |
| 127 | ||
| 128 | ### Adding Arguments | |
| 129 | ||
| 130 | Arguments are positional values: | |
| 131 | ||
| 132 | ```typescript | |
| 133 | // app/Commands/Copy.ts | |
| 134 | import type { CLI } from '@stacksjs/types' | |
| 135 | import process from 'node:process' | |
| 136 | import { log } from '@stacksjs/cli' | |
| 137 | import { ExitCode } from '@stacksjs/types' | |
| 138 | ||
| 139 | export default function (cli: CLI) { | |
| 140 | cli | |
| 141 | .command('copy <source> <destination>', 'Copy files from source to destination') | |
| 142 | .option('--recursive, -r', 'Copy recursively', { default: false }) | |
| 143 | .option('--force, -f', 'Overwrite existing files', { default: false }) | |
| 144 | .action((source: string, destination: string, options) => { | |
| 145 | log.info(`Copying from ${source} to ${destination}`) | |
| 146 | ||
| 147 | if (options.recursive) { | |
| 148 | log.info('Copying recursively...') | |
| 149 | } | |
| 150 | ||
| 151 | if (options.force) { | |
| 152 | log.info('Overwriting existing files...') | |
| 153 | } | |
| 154 | ||
| 155 | // Perform copy operation | |
| 156 | ||
| 157 | log.success('Copy completed!') | |
| 158 | process.exit(ExitCode.Success) | |
| 159 | }) | |
| 160 | ||
| 161 | return cli | |
| 162 | } | |
| 163 | ``` | |
| 164 | ||
| 165 | Usage: | |
| 166 | ||
| 167 | ```bash | |
| 168 | buddy copy ./src ./dist | |
| 169 | buddy copy ./src ./dist --recursive --force | |
| 170 | buddy copy ./src ./dist -rf | |
| 171 | ``` | |
| 172 | ||
| 173 | ### Optional Arguments | |
| 174 | ||
| 175 | Use square brackets for optional arguments: | |
| 176 | ||
| 177 | ```typescript | |
| 178 | cli | |
| 179 | .command('deploy [environment]', 'Deploy to an environment') | |
| 180 | .action((environment: string = 'production') => { | |
| 181 | log.info(`Deploying to ${environment}...`) | |
| 182 | }) | |
| 183 | ``` | |
| 184 | ||
| 185 | ### Variadic Arguments | |
| 186 | ||
| 187 | Accept multiple values: | |
| 188 | ||
| 189 | ```typescript | |
| 190 | cli | |
| 191 | .command('install <packages...>', 'Install packages') | |
| 192 | .action((packages: string[]) => { | |
| 193 | packages.forEach(pkg => { | |
| 194 | log.info(`Installing ${pkg}...`) | |
| 195 | }) | |
| 196 | }) | |
| 197 | ``` | |
| 198 | ||
| 199 | Usage: | |
| 200 | ||
| 201 | ```bash | |
| 202 | buddy install lodash axios vue | |
| 203 | ``` | |
| 204 | ||
| 205 | ## Interactive Prompts | |
| 206 | ||
| 207 | Stacks provides interactive prompts for user input. | |
| 208 | ||
| 209 | ### Confirmation Prompt | |
| 210 | ||
| 211 | ```typescript | |
| 212 | import { confirm } from '@stacksjs/cli' | |
| 213 | ||
| 214 | const shouldContinue = await confirm('Are you sure you want to continue?') | |
| 215 | ||
| 216 | if (shouldContinue) { | |
| 217 | log.info('Continuing...') | |
| 218 | } else { | |
| 219 | log.info('Cancelled.') | |
| 220 | process.exit(ExitCode.Success) | |
| 221 | } | |
| 222 | ``` | |
| 223 | ||
| 224 | ### Text Input | |
| 225 | ||
| 226 | ```typescript | |
| 227 | import { prompt } from '@stacksjs/cli' | |
| 228 | ||
| 229 | const name = await prompt('What is your name?') | |
| 230 | const email = await prompt('What is your email?', { | |
| 231 | default: 'user@example.com', | |
| 232 | }) | |
| 233 | ||
| 234 | log.info(`Hello, ${name} (${email})!`) | |
| 235 | ``` | |
| 236 | ||
| 237 | ### Password Input | |
| 238 | ||
| 239 | ```typescript | |
| 240 | import { password } from '@stacksjs/cli' | |
| 241 | ||
| 242 | const secret = await password('Enter your password:') | |
| 243 | ``` | |
| 244 | ||
| 245 | ### Selection List | |
| 246 | ||
| 247 | ```typescript | |
| 248 | import { select } from '@stacksjs/cli' | |
| 249 | ||
| 250 | const choice = await select('Choose an environment:', [ | |
| 251 | 'development', | |
| 252 | 'staging', | |
| 253 | 'production', | |
| 254 | ]) | |
| 255 | ||
| 256 | log.info(`Selected: ${choice}`) | |
| 257 | ``` | |
| 258 | ||
| 259 | ### Multi-Select | |
| 260 | ||
| 261 | ```typescript | |
| 262 | import { multiselect } from '@stacksjs/cli' | |
| 263 | ||
| 264 | const features = await multiselect('Select features to enable:', [ | |
| 265 | { name: 'TypeScript', value: 'typescript', checked: true }, | |
| 266 | { name: 'ESLint', value: 'eslint', checked: true }, | |
| 267 | { name: 'Testing', value: 'testing' }, | |
| 268 | { name: 'Docker', value: 'docker' }, | |
| 269 | ]) | |
| 270 | ||
| 271 | log.info(`Selected features: ${features.join(', ')}`) | |
| 272 | ``` | |
| 273 | ||
| 274 | ### Complete Interactive Example | |
| 275 | ||
| 276 | ```typescript | |
| 277 | // app/Commands/Init.ts | |
| 278 | import type { CLI } from '@stacksjs/types' | |
| 279 | import process from 'node:process' | |
| 280 | import { confirm, log, multiselect, prompt, select } from '@stacksjs/cli' | |
| 281 | import { ExitCode } from '@stacksjs/types' | |
| 282 | ||
| 283 | export default function (cli: CLI) { | |
| 284 | cli | |
| 285 | .command('init', 'Initialize a new project') | |
| 286 | .action(async () => { | |
| 287 | log.info('Welcome to the project initializer!') | |
| 288 | console.log('') | |
| 289 | ||
| 290 | // Get project name | |
| 291 | const projectName = await prompt('Project name:', { | |
| 292 | default: 'my-project', | |
| 293 | }) | |
| 294 | ||
| 295 | // Choose template | |
| 296 | const template = await select('Choose a template:', [ | |
| 297 | 'minimal', | |
| 298 | 'with-auth', | |
| 299 | 'full-stack', | |
| 300 | 'api-only', | |
| 301 | ]) | |
| 302 | ||
| 303 | // Select features | |
| 304 | const features = await multiselect('Select additional features:', [ | |
| 305 | { name: 'Database (SQLite)', value: 'database', checked: true }, | |
| 306 | { name: 'Authentication', value: 'auth' }, | |
| 307 | { name: 'Testing', value: 'testing', checked: true }, | |
| 308 | { name: 'Docker', value: 'docker' }, | |
| 309 | { name: 'CI/CD', value: 'cicd' }, | |
| 310 | ]) | |
| 311 | ||
| 312 | // Confirm | |
| 313 | console.log('') | |
| 314 | log.info('Configuration:') | |
| 315 | log.info(` Project: ${projectName}`) | |
| 316 | log.info(` Template: ${template}`) | |
| 317 | log.info(` Features: ${features.join(', ') || 'none'}`) | |
| 318 | console.log('') | |
| 319 | ||
| 320 | const confirmed = await confirm('Create project with these settings?') | |
| 321 | ||
| 322 | if (!confirmed) { | |
| 323 | log.warning('Project creation cancelled.') | |
| 324 | process.exit(ExitCode.Success) | |
| 325 | } | |
| 326 | ||
| 327 | // Create project | |
| 328 | log.info('Creating project...') | |
| 329 | // ... project creation logic | |
| 330 | ||
| 331 | log.success(`Project "${projectName}" created successfully!`) | |
| 332 | console.log('') | |
| 333 | log.info('Next steps:') | |
| 334 | log.info(` cd ${projectName}`) | |
| 335 | log.info(' bun install') | |
| 336 | log.info(' buddy dev') | |
| 337 | ||
| 338 | process.exit(ExitCode.Success) | |
| 339 | }) | |
| 340 | ||
| 341 | return cli | |
| 342 | } | |
| 343 | ``` | |
| 344 | ||
| 345 | ## Output Formatting | |
| 346 | ||
| 347 | ### Log Levels | |
| 348 | ||
| 349 | ```typescript | |
| 350 | import { log } from '@stacksjs/cli' | |
| 351 | ||
| 352 | log.info('Information message') // Blue text | |
| 353 | log.success('Success message') // Green text | |
| 354 | log.warning('Warning message') // Yellow text | |
| 355 | log.error('Error message') // Red text | |
| 356 | log.debug('Debug message') // Gray text (only in verbose mode) | |
| 357 | ``` | |
| 358 | ||
| 359 | ### Tables | |
| 360 | ||
| 361 | ```typescript | |
| 362 | import { table } from '@stacksjs/cli' | |
| 363 | ||
| 364 | const users = [ | |
| 365 | { id: 1, name: 'Alice', email: 'alice@example.com', role: 'Admin' }, | |
| 366 | { id: 2, name: 'Bob', email: 'bob@example.com', role: 'User' }, | |
| 367 | { id: 3, name: 'Charlie', email: 'charlie@example.com', role: 'User' }, | |
| 368 | ] | |
| 369 | ||
| 370 | table(users, { | |
| 371 | columns: ['id', 'name', 'email', 'role'], | |
| 372 | headers: ['ID', 'Name', 'Email', 'Role'], | |
| 373 | }) | |
| 374 | ``` | |
| 375 | ||
| 376 | Output: | |
| 377 | ||
| 378 | ``` | |
| 379 | ┌────┬─────────┬─────────────────────────┬───────┐ | |
| 380 | │ ID │ Name │ Email │ Role │ | |
| 381 | ├────┼─────────┼─────────────────────────┼───────┤ | |
| 382 | │ 1 │ Alice │ alice@example.com │ Admin │ | |
| 383 | │ 2 │ Bob │ bob@example.com │ User │ | |
| 384 | │ 3 │ Charlie │ charlie@example.com │ User │ | |
| 385 | └────┴─────────┴─────────────────────────┴───────┘ | |
| 386 | ``` | |
| 387 | ||
| 388 | ### Progress Bars | |
| 389 | ||
| 390 | ```typescript | |
| 391 | import { progress } from '@stacksjs/cli' | |
| 392 | ||
| 393 | const bar = progress('Processing files', { total: 100 }) | |
| 394 | ||
| 395 | for (let i = 0; i <= 100; i++) { | |
| 396 | await sleep(50) // Simulate work | |
| 397 | bar.update(i) | |
| 398 | } | |
| 399 | ||
| 400 | bar.stop('Processing complete!') | |
| 401 | ``` | |
| 402 | ||
| 403 | ### Spinners | |
| 404 | ||
| 405 | ```typescript | |
| 406 | import { spinner } from '@stacksjs/cli' | |
| 407 | ||
| 408 | const spin = spinner('Loading data...') | |
| 409 | spin.start() | |
| 410 | ||
| 411 | // Simulate async work | |
| 412 | await fetchData() | |
| 413 | ||
| 414 | spin.stop('Data loaded!') | |
| 415 | // Or on error: | |
| 416 | // spin.fail('Failed to load data') | |
| 417 | ``` | |
| 418 | ||
| 419 | ### Colored Output | |
| 420 | ||
| 421 | ```typescript | |
| 422 | import { colors } from '@stacksjs/cli' | |
| 423 | ||
| 424 | console.log(colors.blue('Blue text')) | |
| 425 | console.log(colors.red('Red text')) | |
| 426 | console.log(colors.green('Green text')) | |
| 427 | console.log(colors.yellow('Yellow text')) | |
| 428 | console.log(colors.bold('Bold text')) | |
| 429 | console.log(colors.dim('Dimmed text')) | |
| 430 | console.log(colors.underline('Underlined text')) | |
| 431 | ||
| 432 | // Combine styles | |
| 433 | console.log(colors.bold(colors.red('Bold red text'))) | |
| 434 | ``` | |
| 435 | ||
| 436 | ### Boxes | |
| 437 | ||
| 438 | ```typescript | |
| 439 | import { box } from '@stacksjs/cli' | |
| 440 | ||
| 441 | box('Important Message', { | |
| 442 | title: 'Notice', | |
| 443 | padding: 1, | |
| 444 | borderStyle: 'round', | |
| 445 | borderColor: 'yellow', | |
| 446 | }) | |
| 447 | ``` | |
| 448 | ||
| 449 | Output: | |
| 450 | ||
| 451 | ``` | |
| 452 | ╭──────────────────────────────╮ | |
| 453 | │ │ | |
| 454 | │ Notice │ | |
| 455 | │ │ | |
| 456 | │ Important Message │ | |
| 457 | │ │ | |
| 458 | ╰──────────────────────────────╯ | |
| 459 | ``` | |
| 460 | ||
| 461 | ## Command Aliases | |
| 462 | ||
| 463 | Create shorthand aliases for commands: | |
| 464 | ||
| 465 | ```typescript | |
| 466 | cli | |
| 467 | .command('database:migrate', 'Run database migrations') | |
| 468 | .alias('migrate') | |
| 469 | .alias('db:m') | |
| 470 | .action(() => { | |
| 471 | // Migration logic | |
| 472 | }) | |
| 473 | ``` | |
| 474 | ||
| 475 | Usage: | |
| 476 | ||
| 477 | ```bash | |
| 478 | buddy database:migrate | |
| 479 | buddy migrate | |
| 480 | buddy db:m | |
| 481 | ``` | |
| 482 | ||
| 483 | ## Sub-Commands | |
| 484 | ||
| 485 | Organize related commands with namespaces: | |
| 486 | ||
| 487 | ```typescript | |
| 488 | // app/Commands/Database.ts | |
| 489 | export default function (cli: CLI) { | |
| 490 | // Main namespace command | |
| 491 | cli | |
| 492 | .command('database', 'Database management commands') | |
| 493 | .action(() => { | |
| 494 | log.info('Available commands:') | |
| 495 | log.info(' database:migrate - Run migrations') | |
| 496 | log.info(' database:seed - Seed database') | |
| 497 | log.info(' database:reset - Reset database') | |
| 498 | }) | |
| 499 | ||
| 500 | // Sub-commands | |
| 501 | cli | |
| 502 | .command('database:migrate', 'Run database migrations') | |
| 503 | .option('--fresh', 'Drop all tables first') | |
| 504 | .action((options) => { | |
| 505 | if (options.fresh) { | |
| 506 | log.warning('Dropping all tables...') | |
| 507 | } | |
| 508 | log.info('Running migrations...') | |
| 509 | }) | |
| 510 | ||
| 511 | cli | |
| 512 | .command('database:seed', 'Seed the database') | |
| 513 | .option('--class <name>', 'Specific seeder to run') | |
| 514 | .action((options) => { | |
| 515 | log.info('Seeding database...') | |
| 516 | }) | |
| 517 | ||
| 518 | cli | |
| 519 | .command('database:reset', 'Reset the database') | |
| 520 | .action(async () => { | |
| 521 | const confirmed = await confirm('This will delete all data. Continue?') | |
| 522 | if (confirmed) { | |
| 523 | log.info('Resetting database...') | |
| 524 | } | |
| 525 | }) | |
| 526 | ||
| 527 | // Handle unknown sub-commands | |
| 528 | cli.on('database:*', () => { | |
| 529 | log.error('Unknown database command') | |
| 530 | log.info('Run `buddy database` for available commands') | |
| 531 | process.exit(1) | |
| 532 | }) | |
| 533 | ||
| 534 | return cli | |
| 535 | } | |
| 536 | ``` | |
| 537 | ||
| 538 | ## Error Handling | |
| 539 | ||
| 540 | Handle errors gracefully: | |
| 541 | ||
| 542 | ```typescript | |
| 543 | import { ExitCode } from '@stacksjs/types' | |
| 544 | ||
| 545 | export default function (cli: CLI) { | |
| 546 | cli | |
| 547 | .command('risky-operation', 'Perform a risky operation') | |
| 548 | .action(async () => { | |
| 549 | try { | |
| 550 | log.info('Starting operation...') | |
| 551 | ||
| 552 | const result = await riskyFunction() | |
| 553 | ||
| 554 | if (!result.success) { | |
| 555 | log.error(`Operation failed: ${result.error}`) | |
| 556 | process.exit(ExitCode.FatalError) | |
| 557 | } | |
| 558 | ||
| 559 | log.success('Operation completed!') | |
| 560 | process.exit(ExitCode.Success) | |
| 561 | } | |
| 562 | catch (error) { | |
| 563 | log.error('An unexpected error occurred:') | |
| 564 | console.error(error) | |
| 565 | process.exit(ExitCode.FatalError) | |
| 566 | } | |
| 567 | }) | |
| 568 | ||
| 569 | return cli | |
| 570 | } | |
| 571 | ``` | |
| 572 | ||
| 573 | ## Complete Example: Deployment CLI | |
| 574 | ||
| 575 | ```typescript | |
| 576 | // app/Commands/Deploy.ts | |
| 577 | import type { CLI } from '@stacksjs/types' | |
| 578 | import process from 'node:process' | |
| 579 | import { | |
| 580 | box, | |
| 581 | colors, | |
| 582 | confirm, | |
| 583 | log, | |
| 584 | progress, | |
| 585 | select, | |
| 586 | spinner, | |
| 587 | table, | |
| 588 | } from '@stacksjs/cli' | |
| 589 | import { ExitCode } from '@stacksjs/types' | |
| 590 | ||
| 591 | interface DeployOptions { | |
| 592 | environment: string | |
| 593 | force: boolean | |
| 594 | skipTests: boolean | |
| 595 | } | |
| 596 | ||
| 597 | export default function (cli: CLI) { | |
| 598 | cli | |
| 599 | .command('deploy [environment]', 'Deploy the application') | |
| 600 | .option('--force, -f', 'Force deployment without confirmation', { default: false }) | |
| 601 | .option('--skip-tests', 'Skip running tests before deployment', { default: false }) | |
| 602 | .action(async (environment: string | undefined, options: DeployOptions) => { | |
| 603 | // Select environment if not provided | |
| 604 | const env = environment || await select('Select deployment environment:', [ | |
| 605 | 'development', | |
| 606 | 'staging', | |
| 607 | 'production', | |
| 608 | ]) | |
| 609 | ||
| 610 | // Show deployment info | |
| 611 | box(`Deploying to ${colors.bold(env)}`, { | |
| 612 | title: 'Deployment', | |
| 613 | borderColor: env === 'production' ? 'red' : 'blue', | |
| 614 | }) | |
| 615 | ||
| 616 | console.log('') | |
| 617 | ||
| 618 | // Confirm for production | |
| 619 | if (env === 'production' && !options.force) { | |
| 620 | const confirmed = await confirm( | |
| 621 | colors.yellow('You are deploying to PRODUCTION. Are you sure?') | |
| 622 | ) | |
| 623 | ||
| 624 | if (!confirmed) { | |
| 625 | log.warning('Deployment cancelled.') | |
| 626 | process.exit(ExitCode.Success) | |
| 627 | } | |
| 628 | } | |
| 629 | ||
| 630 | // Run tests | |
| 631 | if (!options.skipTests) { | |
| 632 | const testSpinner = spinner('Running tests...') | |
| 633 | testSpinner.start() | |
| 634 | ||
| 635 | try { | |
| 636 | await runTests() | |
| 637 | testSpinner.stop('Tests passed!') | |
| 638 | } | |
| 639 | catch (error) { | |
| 640 | testSpinner.fail('Tests failed!') | |
| 641 | log.error('Fix failing tests before deployment.') | |
| 642 | process.exit(ExitCode.FatalError) | |
| 643 | } | |
| 644 | } | |
| 645 | ||
| 646 | // Build | |
| 647 | const buildSpinner = spinner('Building application...') | |
| 648 | buildSpinner.start() | |
| 649 | ||
| 650 | try { | |
| 651 | await buildApplication() | |
| 652 | buildSpinner.stop('Build complete!') | |
| 653 | } | |
| 654 | catch (error) { | |
| 655 | buildSpinner.fail('Build failed!') | |
| 656 | process.exit(ExitCode.FatalError) | |
| 657 | } | |
| 658 | ||
| 659 | // Deploy | |
| 660 | log.info('Deploying...') | |
| 661 | const bar = progress('Uploading files', { total: 100 }) | |
| 662 | ||
| 663 | for (let i = 0; i <= 100; i += 10) { | |
| 664 | await sleep(200) // Simulate upload | |
| 665 | bar.update(i) | |
| 666 | } | |
| 667 | ||
| 668 | bar.stop('Upload complete!') | |
| 669 | ||
| 670 | // Show deployment summary | |
| 671 | console.log('') | |
| 672 | log.success('Deployment successful!') | |
| 673 | console.log('') | |
| 674 | ||
| 675 | table([ | |
| 676 | { key: 'Environment', value: env }, | |
| 677 | { key: 'Version', value: '1.2.3' }, | |
| 678 | { key: 'URL', value: `https://${env}.example.com` }, | |
| 679 | { key: 'Deployed at', value: new Date().toISOString() }, | |
| 680 | ], { | |
| 681 | columns: ['key', 'value'], | |
| 682 | headers: ['Property', 'Value'], | |
| 683 | }) | |
| 684 | ||
| 685 | process.exit(ExitCode.Success) | |
| 686 | }) | |
| 687 | ||
| 688 | return cli | |
| 689 | } | |
| 690 | ||
| 691 | // Helper functions | |
| 692 | async function runTests() { | |
| 693 | await sleep(2000) | |
| 694 | } | |
| 695 | ||
| 696 | async function buildApplication() { | |
| 697 | await sleep(1500) | |
| 698 | } | |
| 699 | ||
| 700 | function sleep(ms: number) { | |
| 701 | return new Promise(resolve => setTimeout(resolve, ms)) | |
| 702 | } | |
| 703 | ``` | |
| 704 | ||
| 705 | ## Distributing Your CLI | |
| 706 | ||
| 707 | ### As npm Package | |
| 708 | ||
| 709 | Your CLI can be distributed as an npm package: | |
| 710 | ||
| 711 | ```json | |
| 712 | // package.json | |
| 713 | { | |
| 714 | "name": "my-cli", | |
| 715 | "version": "1.0.0", | |
| 716 | "bin": { | |
| 717 | "my-cli": "./dist/cli.js" | |
| 718 | } | |
| 719 | } | |
| 720 | ``` | |
| 721 | ||
| 722 | ### As Binary | |
| 723 | ||
| 724 | Build a standalone binary: | |
| 725 | ||
| 726 | ```bash | |
| 727 | buddy build:cli | |
| 728 | ``` | |
| 729 | ||
| 730 | This creates platform-specific binaries in the `dist/` directory. | |
| 731 | ||
| 732 | ## Next Steps | |
| 733 | ||
| 734 | Now that you know how to build CLIs, continue to: | |
| 735 | ||
| 736 | - [Build a Desktop App](/bootcamp/desktop) - Package your app as a desktop application | |
| 737 | - [Testing How-To](/bootcamp/how-to/testing) - Test your CLI commands | |
| 738 | - [Deployment How-To](/bootcamp/how-to/deploy) - Distribute your CLI | |
| 739 | ||
| 740 | ## Related Documentation | |
| 741 | ||
| 742 | - [Commands Guide](/basics/commands) | |
| 743 | - [CLI Package](/packages/cli) | |