Apparatus Exec

A powerful CLI tool that executes bash commands through predefined shortcuts and filters their output using regex patterns. Designed specifically for LLM-driven development workflows to reduce token usage by filtering out noise and showing only relevant output.

Features

• LLM-Optimized Output - Filters out verbose logs and clutter to reduce token usage in AI conversations
• Shortcuts - Execute command sequences with simple names
• Regex Filtering - Filter command output using configurable regex patterns
• Working Directory Support - Run commands in specific directories
• Token Efficiency - Show only errors, warnings, and critical information to LLMs

Installation

Global Installation (Recommended)

npm install -g @apparatus-technology/exec

After installation, you can use the aex command anywhere:

aex --help

Local Development

git clone <repository>
cd apparatus-exec
bun install
bun run dev --help

Quick Start

1. Initialize Configuration

aex init

This creates an exec.config.yml file with predefined shortcuts and filter patterns.

2. Run a Shortcut

aex backend-build    # Clean and build .NET backend
aex git-status      # Show git status in short format
aex test-frontend   # Run frontend tests

3. List Available Shortcuts

aex nonexistent-shortcut  # Shows all available shortcuts

Configuration

The exec.config.yml file contains two main sections:

Shortcuts

Define command sequences that can be executed by name:

shortcuts:
  backend-build:
    commands:
      - dotnet clean
      - dotnet build
    description: Clean and build .NET backend solution
    working-dir: ./backend
    
  deploy:
    commands:
      - npm run build
      - docker build -t myapp .
      - docker push myapp
    description: Build and deploy application

Filters

Regex patterns to filter command output:

filters:
  - name: Error Messages
    pattern: (?i)error|exception|fail
    description: Captures error messages, exceptions, and failures
    
  - name: Build Errors
    pattern: error CS\d+:
    description: C# compiler errors

Pattern Templates

When initializing, choose from predefined pattern collections:

• General - Common patterns (errors, warnings, IPs, URLs)
• .NET Build Errors - C# compiler and MSBuild errors
• TypeScript Build Errors - TypeScript compiler errors
• JavaScript/Node.js Errors - Runtime errors and npm issues
• Docker Errors - Container and image build failures
• Git Operations - Git command errors and conflicts
• Test Framework Errors - Test failures and coverage issues
• Web Server Errors - HTTP errors and connection issues

Advanced Usage

Custom Configuration File

aex backend-build --config ./custom-config.yml

Multiple Commands in Shortcuts

Commands execute sequentially in the same working directory:

shortcuts:
  full-test:
    commands:
      - npm install      # Install dependencies
      - npm run lint     # Check code style  
      - npm test         # Run tests
      - npm run build    # Build for production
    working-dir: ./frontend

Working Directories

• Relative paths: Resolved from current working directory
• Absolute paths: Used as-is
• No working-dir: Commands run in current directory

Examples

Development Workflow

# Initialize config with .NET and TypeScript patterns
aex init

# Clean and build backend
aex backend-build

# Run tests and see only failures
aex test-backend

# Check git status in short format  
aex git-status

Custom Shortcut Example

shortcuts:
  deploy-staging:
    commands:
      - git pull origin main
      - npm ci
      - npm run build
      - docker build -t myapp:staging .
      - docker push myapp:staging
      - kubectl apply -f k8s/staging/
    description: Deploy to staging environment
    working-dir: .

Output Filtering for LLMs

The primary goal is to reduce token usage when working with LLMs by filtering out verbose, irrelevant output. Only lines matching your configured regex patterns are displayed, dramatically reducing the amount of text sent to AI models.

Without filtering (high token usage):

$ dotnet build
MSBuild version 17.8.5+b5de88f09 for .NET
  Determining projects to restore...
  All projects are up-to-date for restore.
  Apparatus.Exec -> D:\path\to\bin\Debug\net8.0\Apparatus.Exec.dll
  Build succeeded.
      0 Warning(s)
      0 Error(s)
  Time Elapsed 00:00:01.23

With filtering (low token usage):

$ aex backend-build
error CS1002: ; expected
error CS0103: The name 'variableName' does not exist
Build FAILED.
Done

This reduces tokens by 80-90% while preserving critical information for LLMs to understand and respond to issues.

Command Line Options

Usage: aex [options] [command] [shortcut]

Arguments:
  shortcut             Shortcut name to execute

Options:
  -V, --version        Output version number
  -c, --config <path>  Path to YAML config file (default: "exec.config.yml")
  --no-filter          Disable output filtering to see full command output
  -h, --help           Display help

Commands:
  init [options]       Initialize configuration file with pattern templates

Debugging Filters

Use --no-filter to see the complete output when adjusting your regex patterns:

# See full output to understand what to filter
aex backend-build --no-filter

# Then run with filtering to test your patterns
aex backend-build

Development

This project uses Bun for development and compiles to Node.js for distribution.

Development Commands

bun install           # Install dependencies
bun run dev          # Run with TypeScript directly
bun run build        # Compile for Node.js distribution
npm publish          # Publish to npm registry

License

MIT