name: gluegun-patterns description: Gluegun CLI toolkit patterns for TypeScript-powered command-line apps. Use when building CLI tools, creating command structures, implementing template systems, filesystem operations, HTTP utilities, prompts, or plugin architectures with Gluegun. allowed-tools: Read, Write, Edit, Bash, Glob

Gluegun CLI Toolkit Patterns

Provides comprehensive patterns and templates for building TypeScript-powered CLI applications using the Gluegun toolkit. Gluegun offers parameters, templates, filesystem operations, HTTP utilities, prompts, and extensible plugin architecture.

Core Capabilities

Gluegun provides these essential toolbox features:

Parameters - Command-line arguments and options parsing
Template - EJS-based file generation from templates
Filesystem - File and directory operations (fs-jetpack)
System - Execute external commands and scripts
HTTP - API interactions with axios/apisauce
Prompt - Interactive user input with enquirer
Print - Colorful console output with colors/ora
Patching - Modify existing file contents
Semver - Version string manipulation
Plugin System - Extensible command architecture

Instructions

Building a Basic CLI

Initialize Gluegun CLI structure:

import { build } from 'gluegun'

const cli = build()
  .brand('mycli')
  .src(__dirname)
  .plugins('./node_modules', { matching: 'mycli-*', hidden: true })
  .help()
  .version()
  .create()

Create command structure:
- Commands go in src/commands/ directory
- Each command exports a GluegunCommand object
- Use templates from templates/ directory
- Reference template: templates/commands/basic-command.ts.ejs

Implement command with toolbox:

module.exports = {
  name: 'generate',
  run: async (toolbox) => {
    const { template, print, parameters } = toolbox
    const name = parameters.first

    await template.generate({
      template: 'model.ts.ejs',
      target: `src/models/${name}.ts`,
      props: { name }
    })

    print.success(`Generated ${name} model`)
  }
}

Template System

Template file structure:
- Store templates in templates/ directory
- Use EJS syntax: <%= variable %>, <%- unescaped %>
- Reference: templates/toolbox/template-examples.ejs

Generate files from templates:

await template.generate({
  template: 'component.tsx.ejs',
  target: `src/components/${name}.tsx`,
  props: { name, style: 'functional' }
})

Helper functions:
- props.camelCase - camelCase conversion
- props.pascalCase - PascalCase conversion
- props.kebabCase - kebab-case conversion
- Reference: scripts/template-helpers.ts

Filesystem Operations

Common operations (fs-jetpack):

// Read/write files
const config = await filesystem.read('config.json', 'json')
await filesystem.write('output.txt', data)

// Directory operations
await filesystem.dir('src/components')
const files = filesystem.find('src', { matching: '*.ts' })

// Copy/move/remove
await filesystem.copy('template', 'output')
await filesystem.move('old.txt', 'new.txt')
await filesystem.remove('temp')

Path utilities:

filesystem.path('src', 'commands') // Join paths
filesystem.cwd() // Current directory
filesystem.separator // OS-specific separator

HTTP Utilities

API interactions:

const api = http.create({
  baseURL: 'https://api.example.com',
  headers: { 'Authorization': 'Bearer token' }
})

const response = await api.get('/users')
const result = await api.post('/users', { name: 'John' })

Error handling:

if (!response.ok) {
  print.error(response.problem)
  return
}

Interactive Prompts

User input patterns:

// Ask question
const result = await prompt.ask({
  type: 'input',
  name: 'name',
  message: 'What is your name?'
})

// Confirm action
const proceed = await prompt.confirm('Continue?')

// Select from list
const choice = await prompt.ask({
  type: 'select',
  name: 'framework',
  message: 'Choose framework:',
  choices: ['React', 'Vue', 'Angular']
})

Multi-select and complex forms:
- Reference: examples/prompts/multi-select.ts
- See: templates/toolbox/prompt-examples.ts.ejs

Plugin Architecture

Create extensible plugins:

// Plugin structure
export default (toolbox) => {
  const { filesystem, template } = toolbox

  // Add custom extension
  toolbox.myFeature = {
    doSomething: () => { /* ... */ }
  }
}

Load plugins:

cli.plugins('./node_modules', { matching: 'mycli-*' })
cli.plugins('./plugins', { matching: '*.js' })

Plugin examples:
- Reference: examples/plugin-system/custom-plugin.ts
- See: templates/plugins/plugin-template.ts.ejs

Print Utilities

Colorful output:

print.info('Information message')
print.success('Success message')
print.warning('Warning message')
print.error('Error message')
print.highlight('Highlighted text')
print.muted('Muted text')

Spinners and progress:

const spinner = print.spin('Loading...')
await doWork()
spinner.succeed('Done!')

// Or fail
spinner.fail('Something went wrong')

Tables and formatting:

print.table([
  ['Name', 'Age'],
  ['John', '30'],
  ['Jane', '25']
])

System Commands

Execute external commands:

const output = await system.run('npm install')
const result = await system.exec('git status')

// Spawn with options
await system.spawn('npm run build', { stdio: 'inherit' })

Check command availability:

const hasGit = await system.which('git')

File Patching

Modify existing files:

// Add line after pattern
await patching.update('package.json', (content) => {
  const pkg = JSON.parse(content)
  pkg.scripts.build = 'tsc'
  return JSON.stringify(pkg, null, 2)
})

// Insert import statement
await patching.insert('src/index.ts', 'import { Router } from "express"')

Validation Scripts

Use these scripts to validate Gluegun CLI implementations:

scripts/validate-cli-structure.sh - Check directory structure
scripts/validate-commands.sh - Verify command format
scripts/validate-templates.sh - Check template syntax
scripts/test-cli-build.sh - Run full CLI build test

Templates

Command Templates

templates/commands/basic-command.ts.ejs - Simple command
templates/commands/generator-command.ts.ejs - File generator
templates/commands/api-command.ts.ejs - HTTP interaction

Extension Templates

templates/extensions/custom-toolbox.ts.ejs - Toolbox extension
templates/extensions/helper-functions.ts.ejs - Utility functions

Plugin Templates

templates/plugins/plugin-template.ts.ejs - Plugin structure
templates/plugins/plugin-with-commands.ts.ejs - Plugin with commands

Toolbox Templates

templates/toolbox/template-examples.ejs - Template patterns
templates/toolbox/prompt-examples.ts.ejs - Prompt patterns
templates/toolbox/filesystem-examples.ts.ejs - Filesystem patterns

Examples

Basic CLI Example

See examples/basic-cli/ for complete working CLI:

Simple command structure
Template generation
User prompts
File operations

Plugin System Example

See examples/plugin-system/ for extensible architecture:

Plugin loading
Custom toolbox extensions
Command composition

Template Generator Example

See examples/template-generator/ for advanced patterns:

Multi-file generation
Conditional templates
Helper functions

Best Practices

Command Organization
- One command per file
- Group related commands in subdirectories
- Use clear, descriptive command names
Template Design
- Keep templates simple and focused
- Use helper functions for complex logic
- Document template variables
Error Handling
- Check HTTP response status
- Validate user input from prompts
- Provide helpful error messages
Plugin Architecture
- Make plugins optional
- Document plugin interfaces
- Version plugin APIs
Testing
- Test commands in isolation
- Mock filesystem operations
- Validate template output

Security Considerations

Never hardcode API keys in templates
Use environment variables for secrets
Validate all user input from prompts
Sanitize file paths from parameters
Check filesystem permissions before operations

Requirements

Node.js 14+ or TypeScript 4+
Gluegun package: npm install gluegun
EJS for templates (included)
fs-jetpack for filesystem (included)
enquirer for prompts (included)

gluegun-patterns

$ Installer