Mixcli

https://github.com/zhangfisher/mixcli
Admin
Mixcli is a toolkit for developing command line applications, providing command line parsing,...
Tokens:4,021
Snippets:17
Trust Score:8.5
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Implement Command Hooks with MixCommand

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Shows how to add 'before' and 'after' hooks to commands using MixCommand in JavaScript. These hooks are useful for setup, validation, logging, and cleanup. The example requires the MixCommand library and demonstrates asynchronous hook execution.

```javascript
const command = new MixCommand('process')
    .description('Process data')
    .option('-i, --input <file>', 'Input file')
    // Before hook - runs before action
    .before(async ({ args, options, command }) => {
        console.log('Validating input...');
        if (!options.input) {
            throw new Error('Input file required');
        }
        // Setup operations
        command.startTime = Date.now();
    }, true)  // true = applies to subcommands too
    // Main action
    .action(({ options, command }) => {
        console.log('Processing:', options.input);
        // Process data
        return { recordsProcessed: 1000 };
    })
    // After hook - runs after action
    .after(async ({ value, options, command }) => {
        const duration = Date.now() - command.startTime;
        console.log(`Processed ${value.recordsProcessed} records in ${duration}ms`);
        // Cleanup operations
    }, true);
```

--------------------------------

### Add Custom Help Text to MixCli Commands

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Adds custom help text to CLI commands at specified positions (e.g., 'beforeAll', 'afterAll'). This is useful for providing examples, notes, and additional documentation. The .addHelp() method takes the help text content and an options object to control its position and indentation.

```javascript
const cli = new MixCli({
    name: 'mycli',
    version: '1.0.0',
    description: 'My CLI tool'
});

// Add help before all content
cli.addHelp(`
    Examples:
      $ mycli dev --port 3000
      $ mycli build --env production
      $ mycli deploy --target staging
`, {
    pos: 'beforeAll',
    alignIndent: true  // Auto-fix indentation
});

// Add help after all content
cli.addHelp(`
    For more information, visit https://example.com/docs
    Report issues at https://github.com/example/repo/issues
`, {
    pos: 'afterAll',
    alignIndent: 2  // Indent by 2 spaces
});

cli.run();
```

--------------------------------

### Create MixCli Instance with Configuration

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Initializes a new MixCli instance with configuration options for the root command. This includes settings for package discovery in monorepos, global configurations for prompts, error handling, and defining the CLI's name, title, version, and description.

```javascript
import { MixCli } from 'mixcli';

const cli = new MixCli({
    name: "mycli",
    title: ["MyApp CLI Tool      Version: {}", "1.0.0"],
    version: "1.0.0",
    description: "A powerful CLI tool for development",
    // Auto-discover commands in packages matching this pattern
    include: /^\@myapp\//,
    exclude: /test/,
    cliDir: "cli",  // Directory containing command definitions
    context: { globalConfig: true },  // Shared context across commands
    prompt: 'auto',  // Enable prompts when values missing
    logo: String.raw`
        __  __       _    _ ___
       |  \/  |_   _| |  |_ _|
       | |\/| | | | | |   | |
       | |  | | |_| | |___| |
       |_|  |_|\__, |_____|___|
               |___/            `
});

cli.run();
```

--------------------------------

### Configure Command Initial Values (JavaScript)

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Sets initial values for command options, which can be provided statically or dynamically. This allows options to be pre-configured from sources like configuration files or environment variables before user interaction or action execution.

```javascript
const command = new MixCommand('build')
    .description('Build project')
    // Static initial values
    .initial({
        environment: 'production',
        minify: true,
        sourcemap: false
    })
    .option('-e, --environment <env>', 'Environment')
    .option('--minify', 'Minify output')
    .option('--sourcemap', 'Generate sourcemap')
    .action(({ options }) => {
        console.log('Building with options:', options);
    });

// Or use dynamic initialization
const commandWithDynamic = new MixCommand('serve')
    .description('Serve application')
    .initial(() => {
        // Load from config file or environment
        const config = require('./config.json');
        return {
            port: process.env.PORT || config.defaultPort,
            host: config.defaultHost
        };
    })
    .option('-p, --port <port>', 'Server port')
    .option('-h, --host <host>', 'Server host')
    .action(({ options }) => {
        console.log(`Serving on ${options.host}:${options.port}`);
    });
```

--------------------------------

### Discover and Extend Commands Dynamically with MixCLI

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Explains how to find and extend existing commands dynamically in JavaScript using MixCLI, particularly useful for monorepos. It demonstrates waiting for a command to be registered, adding subcommands, and checking for command existence synchronously and asynchronously.

```javascript
// Package A defines a command
const createCommand = (cli) => {
    return new MixCommand('create')
        .description('Create resources')
        .action(() => {
            console.log('Creating...');
        });
};

// Package B extends the command
const extendCreateCommand = async (cli) => {
    // Wait for command to be registered (async discovery)
    const createCmd = await cli.find('create');

    if (createCmd) {
        // Add subcommand to existing command
        const appCmd = new MixCommand('app')
            .description('Create application')
            .option('-n, --name <name>', 'App name')
            .action(({ options }) => {
                console.log('Creating app:', options.name);
            });

        createCmd.addCommand(appCmd);
    }
};

// Check if command exists
if (cli.exists('create')) {
    console.log('Create command is available');
}

// Get command synchronously
const cmd = cli.get('create');
```

--------------------------------

### Listen to Command Registration Events in MixCli

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Subscribes to CLI events, specifically command registration, to implement dynamic behaviors and logging. It requires an instance of MixCli and uses the .on() method to listen for 'register' events. The event handler receives the command's full name and a success flag, logging the registration status.

```javascript
const cli = new MixCli({
    name: 'mycli',
    version: '1.0.0'
});

// Listen for command registration
cli.on('register', (fullname, success) => {
    console.log(`Command registered: ${fullname}`);
    if (success) {
        console.log('Registration successful');
    }
}, { objectify: true });

// Register commands
cli.register(() => {
    const cmd = new MixCommand('test')
        .description('Run tests')
        .action(() => console.log('Running tests...'));
    return cmd;
});

cli.run();
// Output: Command registered: mycli.test
//         Registration successful
```

--------------------------------

### Define Enhanced Action Signatures with MixCommand

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Demonstrates how to define command actions with enhanced signatures in JavaScript using MixCommand. This allows structured access to arguments, options, and context, supporting chained actions and controlling execution flow. It requires the MixCommand library.

```javascript
const command = new MixCommand('deploy')
    .description('Deploy application')
    .option('-e, --env <value>', 'Environment', {
        choices: ['dev', 'staging', 'prod']
    })
    // Enhanced action signature
    .action(({ args, options, value, command }) => {
        console.log('Deploying to:', options.env);
        console.log('Arguments:', args);
        console.log('Command:', command.name());
        return { deployed: true, env: options.env };
    }, {
        id: 'deploy-action',
        enhance: true,
        at: 'append'
    })
    // Chain another action
    .action(({ value, options }) => {
        if (value.deployed) {
            console.log('Deployment successful!');
        }
    }, {
        id: 'post-deploy',
        enhance: true,
        at: 'after'
    });
```

--------------------------------

### Execute Commands Across Multiple Directories (JavaScript)

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Facilitates running commands in multiple working directories, ideal for monorepo management. This can be achieved using the built-in '--work-dirs' option or programmatically by registering commands.

```javascript
// Built-in --work-dirs option allows running in multiple directories
// Usage from command line:
// mycli build --work-dirs packages/app,packages/lib,packages/utils

const buildCommand = new MixCommand('build')
    .description('Build packages')
    .option('-w, --watch', 'Watch mode')
    .action(({ options, command }) => {
        const cwd = process.cwd();
        console.log(`Building in ${cwd}`);
        console.log('Watch mode:', options.watch);
        // Build logic runs in each directory specified by --work-dirs
    });

// Or use programmatically
cli.register(() => buildCommand);

// Execute: mycli build --work-dirs ./packages/app,./packages/lib
// The action runs twice: once in packages/app, once in packages/lib
```

--------------------------------

### Define Command Options with Auto-Prompts

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Defines command options with automatic prompt generation using MixCli. The framework infers prompt types from option definitions and generates interactive prompts when values are missing, supporting various input types like text, select, multi-select, toggle, and number.

```javascript
const command = new MixCommand('create')
    .description('Create a new project')
    // Text input with validation
    .option('-n, --name <value>', 'Project name', {
        required: true,
        prompt: {
            type: 'text',
            validate: value => value.length >= 3 || 'Name must be at least 3 characters'
        }
    })
    // Select from choices
    .option('-f, --framework <value>', 'Framework', {
        choices: ['vue', 'react', 'angular'],
        prompt: 'select'  // Auto-generates select prompt
    })
    // Multi-select
    .option('--features <values...>', 'Features', {
        choices: ['router', 'vuex', 'typescript', 'eslint'],
        prompt: 'multiselect'
    })
    // Boolean toggle
    .option('--git', 'Initialize git repository', {
        prompt: {
            type: 'toggle',
            message: 'Initialize git?',
            active: 'yes',
            inactive: 'no'
        }
    })
    // Number input
    .option('--port <number>', 'Port number', {
        default: 8080,
        prompt: 'number'
    })
    .action(({ options }) => {
        console.log('Creating project:', options);
    });
```

--------------------------------

### Add Custom Prompts to Commands (JavaScript)

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Integrates custom interactive prompts into a command, enabling complex user input flows and conditional prompting. Supports various prompt types like text, select, and confirm, with validation and initial values.

```javascript
const command = new MixCommand('setup')
    .description('Setup project configuration')
    .prompt([
        {
            type: 'text',
            name: 'projectName',
            message: 'What is your project name?',
            initial: 'my-project',
            validate: value => value.length > 0 || 'Required'
        },
        {
            type: 'select',
            name: 'packageManager',
            message: 'Which package manager?',
            choices: [
                { title: 'npm', value: 'npm' },
                { title: 'yarn', value: 'yarn' },
                { title: 'pnpm', value: 'pnpm' }
            ]
        },
        {
            type: prev => prev === 'npm' ? 'confirm' : null,
            name: 'saveExact',
            message: 'Save exact versions?'
        }
    ])
    .action(({ options }) => {
        console.log('Setup configuration:', options);
        // options includes all prompt responses
    });
```

--------------------------------

### Create Nested Commands with MixCommand

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Illustrates how to build hierarchical command structures in JavaScript using MixCommand. This allows for parent and child commands, enabling complex CLI tools with multiple subcommand levels. The code defines a root command with nested 'dev' commands ('app' and 'lib').

```javascript
const rootCommand = (cli) => {
    // Parent command
    const devCmd = new MixCommand('dev')
        .description('Development commands')
        .option('--verbose', 'Verbose output')
        .action(() => {
            console.log('Use dev app or dev lib subcommand');
        });

    // Child command 1
    const appCmd = new MixCommand('app')
        .description('Run app in dev mode')
        .option('-p, --port <port>', 'Port', { default: 3000 })
        .action(({ options }) => {
            console.log(`Starting app on port ${options.port}`);
        });

    // Child command 2
    const libCmd = new MixCommand('lib')
        .description('Run library in dev mode')
        .option('-m, --module <type>', 'Module type', {
            choices: ['esm', 'commonjs', 'umd']
        })
        .action(({ options }) => {
            console.log(`Building ${options.module} library`);
        });

    devCmd.addCommand(appCmd);
    devCmd.addCommand(libCmd);

    return devCmd;
};

cli.register(rootCommand);
// Usage: mycli dev app --port 4000
// Usage: mycli dev lib --module esm
```

--------------------------------

### Register Commands with MixCli Instance

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Registers command definitions with the MixCli instance. Commands can be defined as functions that return MixCommand instances or arrays of commands. This allows for modular command definition and registration.

```javascript
import { MixCommand } from 'mixcli';

// Command definition function
const devCommand = (cli) => {
    const cmd = new MixCommand('dev')
        .description('Run application in development mode')
        .option('-p, --port <port>', 'Server port', {
            default: 3000,
            prompt: true
        })
        .option('-h, --host <host>', 'Server host', {
            default: 'localhost',
            prompt: 'text'
        })
        .action(({ args, options, command }) => {
            console.log(`Starting dev server on ${options.host}:${options.port}`);
            // Application logic here
        });

    return cmd;
};

// Register the command
cli.register(devCommand);

// Register multiple commands
const commands = (cli) => {
    const cmd1 = new MixCommand('build').description('Build project');
    const cmd2 = new MixCommand('test').description('Run tests');
    return [cmd1, cmd2];
};

cli.register(commands);
```

--------------------------------

### Control Prompt Display in Commands (JavaScript)

Source: https://context7.com/zhangfisher/mixcli/llms.txt

Manages the visibility of interactive prompts for commands, essential for CI/CD or batch operations. Prompts can be explicitly enabled or disabled per command, or globally via CLI configuration.

```javascript
const command = new MixCommand('deploy')
    .description('Deploy application')
    .enablePrompts()  // Enable all prompts for this command
    .option('-e, --env <value>', 'Environment', {
        choices: ['dev', 'prod'],
        prompt: true
    })
    .action(({ options }) => {
        console.log('Deploying to:', options.env);
    });

// Disable prompts for non-interactive environments
const batchCommand = new MixCommand('batch-process')
    .description('Process in batch mode')
    .disablePrompts()  // Disable all prompts
    .option('-i, --input <file>', 'Input file', {
        required: true  // Will error if not provided, won't prompt
    })
    .action(({ options }) => {
        console.log('Processing:', options.input);
    });

// Global disable via command line: mycli deploy --disable-prompts
// Global disable via CLI config:
const cli = new MixCli({
    name: 'mycli',
    prompt: false  // Disable all prompts globally
});
```
Tokens:
Raw