This framework addresses the challenge of building robust, type-safe Command Line Interfaces (CLIs) that integrate seamlessly with AI agents. It targets developers seeking to create efficient and discoverable CLIs, offering significant benefits in reduced token consumption for AI interactions and simplified development workflows.

How It Works

incur is a TypeScript framework for building Command Line Interfaces (CLIs) designed for both human and AI agent interaction. Its core approach centers on robust schema definition using Zod for arguments, options, environment variables, and output. This schema-driven design ensures type safety, automatic validation, and well-formed I/O, crucial for reliable agent parsing. A key differentiator is its default TOON output format, which is significantly more token-efficient than JSON, reducing AI processing costs. incur also provides built-in, automatic mechanisms for agent discovery (via skills add or MCP sync) and suggests relevant next steps through Call-to-Actions (CTAs), streamlining agent workflows. It supports mounting HTTP APIs as CLIs and serving CLIs as APIs, offering architectural flexibility.

Quick Start & Requirements

• Primary install: npm i incur, pnpm i incur, or bun i incur.
• Prerequisites: Node.js environment (implied by package managers). No specific hardware, OS, or CUDA requirements are listed.

Highlighted Details

• Token Efficiency: Defaults to the TOON output format, which is designed to be human-readable yet easily parsable by agents, claiming up to 60% fewer tokens than JSON. This, combined with optimized discovery, leads to significant session cost savings (up to 3x fewer tokens).
• Schema-Driven Development: Leverages Zod schemas for all CLI inputs (arguments, options, environment variables) and outputs. This ensures strict type safety, automatic validation, and predictable data structures for both developers and AI agents.
• Agent Integration: Features automatic agent discovery mechanisms (skills add, mcp add, --llms flag) and supports Call-to-Actions (CTAs) to guide agent decision-making after command execution.
• Versatile API Mounting: Allows mounting existing HTTP server frameworks (like Hono) directly as CLI commands or serving CLIs as Fetch API handlers, promoting code reuse and interoperability.
• Global Options & Features: Provides a consistent set of global flags (--help, --format, --verbose, --llms, --schema) and features like output filtering and token-based pagination.

Maintenance & Community

No specific details regarding maintainers, sponsorships, or community channels (e.g., Discord, Slack) are present in the provided README.

Licensing & Compatibility

• License: MIT.
• Compatibility: The MIT license is highly permissive, generally allowing for commercial use and integration within closed-source projects without significant restrictions.

Limitations & Caveats

The API Reference section is marked as "TODO," suggesting potential for API evolution. While designed for agent integration, the practical effectiveness for complex agent orchestration will depend on the specific agent's capabilities and incur's integration points.