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:

typescript

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:

typescript

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:

typescript

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):

typescript

// 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:

typescript

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

HTTP Utilities

•

API interactions:

typescript

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:

typescript

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

Interactive Prompts

•

User input patterns:

typescript

// 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:

typescript

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

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

•

Load plugins:

typescript

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:

typescript

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:

typescript

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

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

•

Tables and formatting:

typescript

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

System Commands

•

Execute external commands:

typescript

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:

typescript

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

File Patching

•Modify existing files:

typescript

// 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

Gluegun CLI Toolkit Patterns

Core Capabilities

Instructions

Building a Basic CLI

Template System

Filesystem Operations

HTTP Utilities

Interactive Prompts

Plugin Architecture

Print Utilities

System Commands

File Patching

Validation Scripts

Templates

Command Templates

Extension Templates

Plugin Templates

Toolbox Templates

Examples

Basic CLI Example

Plugin System Example

Template Generator Example

Best Practices

Security Considerations

Requirements

Related Documentation