Aperture

A CLI that generates commands from OpenAPI specifications.

Aperture parses OpenAPI 3.x specs once, caches them, and exposes every operation as a CLI command with structured JSON output. Built for automation: AI agents, scripts, CI/CD pipelines.

Why Aperture?

Fast: Sub-10ms startup time. Binary-cached specs eliminate parsing overhead.

Small: < 6 MB static binary (default features). No runtime dependencies.

Correct: Structured JSON output. Machine-readable errors. Predictable exit codes.

Secure: Credentials resolved from environment variables only—never stored in config.

Agent-First: Self-describing capability manifests. Batch operations. Idempotency support.

Performance

Metric	Value
Binary size	< 6 MB (default features, all platforms)
Startup time	< 5 ms
Memory (typical)	4-8 MB
Spec loading	O(1) from binary cache

Quick Start

# Install
cargo install aperture-cli

# Register an API
aperture config add petstore https://petstore3.swagger.io/api/v3/openapi.json

# Configure authentication
aperture config set-secret petstore api_key --env PETSTORE_API_KEY

# Discover available operations
aperture api petstore --describe-json

# Execute a command
aperture api petstore pet get-pet-by-id --petId 1

Agent Integration

Aperture provides features specifically for programmatic use:

# Get capability manifest (for agent discovery)
aperture api my-api --describe-json

# Structured errors (for programmatic handling)
aperture api my-api --json-errors users list

# Preview without executing
aperture api my-api --dry-run users create --name "Test"

# Batch operations with concurrency control
aperture api my-api --batch-file operations.json --batch-concurrency 10

See Agent Integration Guide for patterns and examples.

Installation

Homebrew (macOS/Linux)

brew install kioku/tap/aperture

cargo-binstall (Pre-built Binaries)

cargo binstall aperture-cli

Nix

# Install directly
nix profile install github:kioku/aperture

# With JQ support
nix profile install github:kioku/aperture#aperture-jq

# With all features
nix profile install github:kioku/aperture#aperture-full

From crates.io

cargo install aperture-cli

From Source

git clone https://github.com/kioku/aperture.git
cd aperture
cargo install --path .

Optional Features

# Full JQ filtering support
cargo install aperture-cli --features jq

# OpenAPI 3.1 support
cargo install aperture-cli --features openapi31

# Both
cargo install aperture-cli --features "jq openapi31"

Documentation

Document	Description
User Guide	Day-to-day usage, commands, output formats
Agent Integration	Capability manifests, batch ops, integration patterns
Security Model	Authentication, secrets, cache security
Configuration	URLs, environments, cache, command mapping
Debugging	Request/response logging, troubleshooting
Architecture	Technical design and internals
Contributing	Development setup, testing, guidelines

Project Status

Experimental: Core functionality is implemented and tested. API and features may evolve based on usage and feedback.

License

MIT License. See LICENSE for details.

aperture-cli 0.1.9