How It Works

cli4ai is a package manager that makes AI tools installable with a single command. It wraps CLI tools as MCP servers automatically, so your AI agent can use them instantly.

Architecture Overview

cli4ai consists of three main parts:

CLI Framework

The cli4ai command that installs, manages, and runs packages.

Package Registry

A collection of tools that can be installed and used immediately.

MCP Adapter

Automatically converts CLI tools into MCP servers for AI agents.

The Package Manifest

Every package is defined by a cli4ai.json manifest:

{
  "name": "slack",
  "version": "1.0.0",
  "description": "Slack integration for AI agents",
  "entry": "run.ts",
  "runtime": "bun",
  "commands": {
    "channels": {
      "description": "List Slack channels"
    },
    "post": {
      "description": "Post a message",
      "args": [
        { "name": "channel", "required": true },
        { "name": "message", "required": true }
      ]
    }
  },
  "env": {
    "SLACK_BOT_TOKEN": {
      "required": true,
      "description": "Slack bot token (xoxb-...)"
    }
  },
  "mcp": {
    "enabled": true,
    "transport": "stdio"
  }
}

The manifest defines:

  • Metadata - Name, version, description
  • Commands - Available operations with arguments
  • Environment - Required credentials and config
  • MCP settings - How to expose tools to AI agents

Installation Flow

When you run cli4ai add slack:

1

Resolve package

Searches local registries, then npm for @cli4ai/slack

2

Install to packages directory

Copies or symlinks to .cli4ai/packages/slack/ (local) or ~/.cli4ai/packages/slack/ (global)

3

Install dependencies

Runs bun install for npm dependencies

4

Check peer dependencies

Verifies system tools are installed (e.g., gh, ffmpeg)

5

Update lockfile

Records exact version in cli4ai.lock for reproducibility

Command Execution

When you run cli4ai run slack post "#general" "Hello!":

1. Find package (local → global → npm)
2. Load cli4ai.json manifest
3. Check required secrets (prompt if missing)
4. Inject secrets as environment variables
5. Execute: bun run /path/to/slack/run.ts post "#general" "Hello!"
6. Return JSON output

Routines (Workflow Orchestration)

Routines are a thin orchestration layer on top of cli4ai run. They let you chain multiple commands (and optionally other executables) into a named workflow, capture step outputs, and feed results into later steps via templates.

Routines live in ./.cli4ai/routines/ (project) or ~/.cli4ai/routines/ (global). Use cli4ai routines run <name> to execute them.

Read the full routines spec →

Secrets Management

cli4ai provides secure credential storage:

# Store a secret (encrypted with AES-256-GCM)
cli4ai secrets set SLACK_BOT_TOKEN

# Secrets are machine-specific (tied to hostname + username)
# Environment variables always take precedence

When running a tool:

  1. Check if required env vars are set
  2. If not, check the encrypted vault
  3. If still missing, prompt the user
  4. Save new secrets to vault for next time
  5. Inject all secrets as environment variables

Local vs Global Installation

Aspect Local (cli4ai add) Global (cli4ai add -g)
Location .cli4ai/packages/ ~/.cli4ai/packages/
Lockfile Yes (cli4ai.lock) No
Scope Project-specific System-wide
Use case Reproducible project setups Personal tools always available

Output Format

All cli4ai tools output JSON for easy parsing by AI agents:

// Success
{
  "channels": [
    { "id": "C123", "name": "general" },
    { "id": "C456", "name": "random" }
  ]
}

// Error
{
  "error": {
    "code": "AUTH_FAILED",
    "message": "Invalid Slack token"
  }
}

Error codes are standardized across all packages for consistent handling.

Next Steps