@oxog/cli

Modern, type-safe CLI framework with @oxog ecosystem integration, plugin architecture, and beautiful output

@oxog/cli is a comprehensive command-line interface framework designed for modern TypeScript applications. It provides a fluent builder API, full TypeScript support, built-in spinner and logging utilities, and a micro-kernel plugin architecture. Built on the @oxog ecosystem for seamless integration with other @oxog packages.

✨ Features

• @oxog Ecosystem Integration - Leverages @oxog/types, @oxog/emitter, @oxog/plugin, and @oxog/pigment for type-safe, consistent APIs
• Full TypeScript Support - Type-safe commands, arguments, and options with utility types from @oxog/types
• Plugin Architecture - Micro-kernel design compatible with @oxog/plugin standards
• Event-Driven - Powered by @oxog/emitter for flexible event handling with wildcard support
• Beautiful Output - Built-in colors, spinners, progress bars, and structured logging
• Robust Parsing - Advanced argument parsing with validation and coercion
• Nested Commands - Support for complex command hierarchies
• Middleware System - Pre/post-processing hooks for commands
• AI-Native Design - Optimized for both humans and AI assistants

📦 Installation

npm install @oxog/cli

Peer Dependencies

@oxog/cli uses peer dependencies from the @oxog ecosystem. If not already installed, add them:

npm install @oxog/types @oxog/emitter @oxog/plugin @oxog/pigment

These packages provide:

• @oxog/types - Common TypeScript utilities (MaybePromise, Unsubscribe, DeepPartial, etc.)
• @oxog/emitter - Type-safe event emitter with async support and wildcard patterns
• @oxog/plugin - Micro-kernel plugin system interfaces
• @oxog/pigment - Terminal styling with chainable API (Chalk-compatible)

🚀 Quick Start

import { cli } from '@oxog/cli';

const app = cli('myapp')
  .version('1.0.0')
  .describe('My awesome CLI application');

app.command('greet')
  .describe('Greet someone')
  .argument('<name>', 'Name of the person to greet')
  .option('--loud', 'Shout the greeting')
  .action(({ args, options }) => {
    const message = `Hello, ${args.name}!`;
    console.log(options.loud ? message.toUpperCase() : message);
  });

app.run();

🔌 Plugins

Enhance your CLI with powerful plugins:

import { cli } from '@oxog/cli';
import { colorPlugin, spinnerPlugin, loggerPlugin } from '@oxog/cli/plugins';

const app = cli('myapp')
  .use(colorPlugin())    // Beautiful colored output
  .use(spinnerPlugin())  // Loading spinners
  .use(loggerPlugin());  // Structured logging

app.command('deploy')
  .describe('Deploy to production')
  .action(async ({ spinner, logger }) => {
    const spin = spinner.start('Deploying...');
    logger.info('Starting deployment...');

    await deploy();

    spin.succeed('Deployed!');
    logger.info('Deployment complete!');
  });

📚 Documentation

• Getting Started Guide
• API Reference
• Plugin Development
• Examples

Available Plugins

Core Plugins:

• helpPlugin - Automatic help text generation
• versionPlugin - Version display support
• validationPlugin - Argument and option validation

Optional Plugins:

• colorPlugin - Terminal styling powered by @oxog/pigment (Chalk-compatible)
• spinnerPlugin - Elegant loading indicators
• loggerPlugin - Structured logging with levels
• middlewarePlugin - Command middleware support
• promptPlugin - Interactive prompts (input, select, confirm, etc.)
• progressPlugin - Progress bars with ETA and rate display
• tablePlugin - Formatted table output with multiple border styles
• configPlugin - Config file support (JSON, YAML, TOML, .env)
• completionPlugin - Shell completion generation (bash, zsh, fish)

🔗 @oxog Ecosystem Integration

@oxog/cli re-exports useful types from the @oxog ecosystem for convenience:

// Type utilities from @oxog/types
import type {
  MaybePromise,
  DeepPartial,
  DeepReadonly,
  Unsubscribe,
  JsonValue,
  EventMap,
} from '@oxog/cli';

// Event emitter from @oxog/emitter
import { Emitter, createEmitter } from '@oxog/cli';

// Terminal styling from @oxog/pigment
import { pigment, createPigment } from '@oxog/cli';

// Or use directly from ecosystem packages
import { Emitter } from '@oxog/emitter';
import pigment from '@oxog/pigment';
import type { MaybePromise } from '@oxog/types';

Using Terminal Styling

The color plugin provides @oxog/pigment for beautiful terminal output:

import { cli } from '@oxog/cli';
import { colorPlugin } from '@oxog/cli/plugins';

const app = cli('myapp').use(colorPlugin());

app.command('status').action(({ pigment, color }) => {
  // @oxog/pigment chainable API (recommended)
  console.log(pigment.red.bold('Error!'));
  console.log(pigment.green.italic('Success!'));
  console.log(pigment.hex('#ff6600').underline('Custom color'));

  // Legacy API (backward compatible)
  console.log(color.red('Error'));
  console.log(color.green('Success'));
});

Using the Event System

The kernel uses @oxog/emitter internally for event handling:

import { cli } from '@oxog/cli';

const app = cli('myapp');

// Subscribe to events
app.kernel.on('command:before', (data) => {
  console.log('Running command:', data);
});

// Emit custom events
await app.kernel.emit('custom:event', { foo: 'bar' });

🧪 Testing

The project has 100% test coverage with 664 passing tests.

npm test
npm run test:coverage

🏗️ Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Watch mode
npm run dev

📝 License

MIT © 2026 Ersin Koç

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.