apexe

Outside-In CLI-to-Agent Bridge — automatically wraps existing CLI tools into governed apcore modules, served via MCP.

What is apexe?

apexe scans any CLI tool on your system (e.g., git, curl, ls, jq), deterministically extracts its command structure, flags, and arguments — then exposes them as governed MCP tools that AI agents can invoke safely.

No LLM required for scanning. No changes to the CLI tools. Zero-config governance.

Key capabilities

• Scan — Three-tier deterministic engine (--help → man pages → shell completions) with 4 built-in parsers (GNU, Click, Cobra, Clap)
• Schema — Generates JSON Schema with type mapping, format hints (path, uri), defaults, enums, and required fields
• Serve — MCP server via apcore-mcp (stdio / streamable-http / SSE) with an Explorer UI, plus an A2A agent server via apcore-a2a. Servers bind localhost by default; transport authentication is available via the apcore library API
• Govern — Behavioral annotations (readonly/destructive/idempotent), flag boosting (--force → requires_approval), fail-closed default-deny ACL, a JSONL audit trail of executions and ACL allow/deny decisions (input hashed, log 0o600), Module::preview() dry-run for destructive commands
• Isolate — every wrapped subprocess runs with the environment scrubbed to a base allowlist (secrets don't leak to tools), no shell (direct argv + injection filtering), output capped at 64 MiB, and a hard timeout that actually kills the process (kill_on_drop); circuit breaker + retry middleware on by default, optional /metrics + /usage
• AI Guidance — Every error includes ai_guidance to help agents self-correct; non-zero exit codes return stderr context

Built on the apcore ecosystem

Installation

Requires Rust 1.75+ and Cargo.

git clone https://github.com/aiperceivable/apexe.git
cd apexe
cargo install --path .
apexe --version

Quick Start

# Scan git — extracts commands, flags, types, annotations
apexe scan git

# See what was generated
apexe list

# Start MCP server (Claude Desktop / Cursor)
apexe serve

# Or HTTP with browser-based tool explorer
apexe serve --transport http --port 8000 --explorer

Claude Desktop integration

apexe serve --show-config claude-desktop
# Copy output to ~/Library/Application Support/Claude/claude_desktop_config.json
# Restart Claude Desktop — git commands appear as MCP tools

Cursor integration

apexe serve --show-config cursor
# Add to Cursor's MCP settings

Commands

apexe scan <TOOLS>...

Scan CLI tools and generate binding files + ACL rules.

apexe scan ls jq curl                   # Scan multiple tools
apexe scan git --depth 3               # 3 levels of subcommands (default: 2, max: 5)
apexe scan git --no-cache              # Force re-scan
apexe scan git --format json           # Output as JSON (also: yaml, table)
apexe scan git --output-dir ./out      # Custom output directory
apexe scan git --skills-dir ./out      # Also write .claude/skills/<id>/SKILL.md per module

apexe serve

Start MCP server for scanned tools.

apexe serve                                         # stdio (default)
apexe serve --transport http --port 8000             # HTTP
apexe serve --transport http --port 8000 --explorer  # HTTP + browser UI
apexe serve --transport sse --port 8000              # Server-Sent Events
apexe serve --show-config claude-desktop             # Print integration config
apexe serve --name my-tools                          # Custom server name
apexe serve --transport http --metrics                # + /metrics (Prometheus) and /usage
apexe serve --no-circuit-breaker --no-retry           # Disable resilience middleware

apexe a2a

Start an A2A agent server for scanned tools. Shares governance (ACL, logging, audit) with apexe serve via the same Executor.

apexe a2a                                       # http://127.0.0.1:8000 (default)
apexe a2a --url http://0.0.0.0:9000 --explorer  # Custom bind address + browser UI
apexe a2a --acl ~/.apexe/acl.yaml               # Governed by an ACL policy
apexe a2a --cors-origin https://example.com     # Allow a browser origin

A2A has no interactive elicitation transport, so there is no --enable-approval flag on apexe a2a (it's available on apexe serve, and on A2A only via the library ApprovalStore API). See docs/user-manual.md.

apexe list

List registered modules.

apexe list                  # Table format
apexe list --format json    # JSON format

apexe config

Show or initialize configuration.

apexe config --show     # Print resolved config (YAML)
apexe config --init     # Create ~/.apexe/config.yaml

How It Works

CLI Tool Binary
      |
      v
+--------------------+
|   Scanner Engine   |  <-- Tier 1: --help (GNU/Click/Cobra/Clap)
|                    |  <-- Tier 2: man pages (DESCRIPTION + OPTIONS)
|                    |  <-- Tier 3: shell completions (subcommand discovery)
+---------+----------+
          |  ScannedCLITool
          v
+--------------------+
|   Adapter Layer    |  <-- module IDs, JSON Schema, annotations, display metadata
+---------+----------+
          |  ScannedModule (apcore-toolkit)
          |
    +-----+-----+
    |           |
    v           v
+--------+  +------------------+
| Output |  |   MCP Server     |
| .yaml  |  | apcore-mcp       |
| ACL    |  | stdio/http/sse   |
| Audit  |  | middleware+auth   |
+--------+  +------------------+

Behavioral annotations

Schema generation

Configuration

Resolved in 4 tiers (highest wins): CLI flags > env vars > config file > defaults

apexe config --init    # Creates ~/.apexe/config.yaml

File Locations

Examples

See examples/README.md for full details.

Developer Guide

Build & Test

cargo build                                             # Build
cargo test --all-features                               # Run tests (~338)
cargo test -- --include-ignored                         # Include integration tests
cargo clippy --all-targets --all-features -- -D warnings  # Lint
cargo fmt --all -- --check                              # Format check
cargo run --example programmatic                        # Run example

Adding a Custom Parser

Implement the CliParser trait in src/scanner/protocol.rs:

pub trait CliParser: Send + Sync {
    fn name(&self) -> &str;
    fn can_parse(&self, help_text: &str) -> bool;
    fn parse(&self, help_text: &str, tool_name: &str) -> anyhow::Result<ParsedHelp>;
    fn priority(&self) -> u32; // lower = tried first
}

Logging

RUST_LOG=debug apexe scan git
apexe --log-level trace scan git

Documentation

Architecture & Design

Feature Specs

License

Apache-2.0