apix

apix is a local-first Rust CLI for API discovery and execution, designed for both AI agents and human developers.

It converts monolithic OpenAPI 3.0/3.1 specs into a file-system-native markdown vault, so API docs can be explored directly from the terminal without scraping web UIs or loading huge JSON blobs into context.

apix follows a progressive disclosure workflow:

• search and ls to discover APIs and routes with low token cost
• peek for condensed required inputs
• show for full endpoint/type docs only when needed
• call to execute requests directly from route metadata

Vaults are plain markdown files on disk (with YAML frontmatter), so they work well with standard shell tools (ls, cat, grep) and remain usable offline after pull/import.

Features

• Import vaults from OpenAPI 3.0/3.1 specs (apix import)
• Browse endpoint/type docs (apix show, apix peek)
• Search local vault content (apix grep)
• Execute HTTP calls from vault frontmatter (apix call)
• Sync registry + namespaces with sparse-checkout (apix update, apix pull)
• Shell completions (apix completions)
• Auto-initializes ~/.apix on first use

Install

curl | sh

Install script is maintained in the web repo.

Latest:

curl -fsSL https://apix.sh/install | sh

Pinned version:

curl -fsSL https://apix.sh/install | sh -s -- --version v0.1.0

Custom install directory:

curl -fsSL https://apix.sh/install | sh -s -- --bin-dir "$HOME/.local/bin"

Homebrew

brew tap apix-sh/tap
brew install apix

Explicit form:

brew install apix-sh/tap/apix

Build from source

Prerequisites:

• Rust toolchain (rustup, cargo, rustc)

Build:

cargo build --release

Binary path:

./target/release/apix

Verify install

apix --version
apix --help

Quick Start

# Show help
cargo run -- --help

# Initialize config/home explicitly (optional)
cargo run -- init

# Import a local vault from an OpenAPI 3.0/3.1 spec
cargo run -- import tests/fixtures/petstore.json --name petstore

# Import directly into a vault repo worktree
cargo run -- import tests/fixtures/petstore.json --name petstore --output /path/to/vault

# Show full route markdown
cargo run -- show petstore/v1/pets/GET

# Show condensed view (frontmatter + required request fields)
cargo run -- peek petstore/v1/pets/{petId}/GET

# Full-text grep within a namespace
cargo run -- grep petstore pet --limit 20 --source .local

# Indexed search across sources
cargo run -- search pet

# List local inventory
cargo run -- ls
cargo run -- ls --source .local
cargo run -- ls petstore

# List detailed routes for a namespace/version
cargo run -- ls petstore/v1
cargo run -- ls petstore/v1 --source core

# Filter routes by path prefix
cargo run -- ls petstore/v1/pet
cargo run -- ls petstore/v1/store/order

Command Reference

• apix search <query> [--source <name>] [--all-sources] [--no-auto-update]: Search indexed APIs
• apix update [--source <name>] [--all-sources]: Clone/pull source registry metadata
• apix pull <namespace>[/<version>] [--source <name>]: Sparse-checkout a namespace (or specific version) from a source (default: core)
• apix import <source> --name <namespace> [--output <vault_root>] [--overwrite]: Generate vault files from an OpenAPI 3.0/3.1 JSON or YAML spec
• apix ls [namespace|namespace/version[/path...]] [--source <name>]: List local inventory or detailed routes
• apix info <namespace/version> [--source <name>]: Print API metadata from frontmatter
• apix show <route> [--source <name>]: Print full markdown for a route/type file
• apix peek <route> [--source <name>]: Print frontmatter + condensed required input info
• apix grep <namespace> <query> [--limit N] [--source <name>]: Search local markdown files
• apix call <route> ... [--source <name>]: Execute HTTP request resolved from route frontmatter
• apix completions <bash|zsh|fish|elvish|powershell>: Generate shell completions
• apix init: Create ~/.apix structure and default config
• apix source add/remove/list: Manage third-party sources
• apix registry rebuild [--source <name>] [--path <vault_root>]: Rebuild registry index from a source root or vault repo path

Route Format

Route strings are slash-separated.

Short form:

<namespace>/<version>/<path segments>/<METHOD>

Explicit source form:

<source>/<namespace>/<version>/<path segments>/<METHOD>

Example:

petstore/v1/pets/{petId}/GET
core/petstore/v1/pets/{petId}/GET

apix call Examples

# Route with literal path segment auto-mapped to {id}
cargo run -- call demo/v1/items/item_123/GET

# Explicit path/query/header/body flags
cargo run -- call demo/v1/items/{id}/POST \
  -p id=item_123 \
  -q expand=full \
  -H "Authorization: Bearer <token>" \
  -d '{"name":"item"}'

# Body from stdin
echo '{"name":"item"}' | cargo run -- call demo/v1/items/{id}/POST -p id=item_123 -d @-

# Body from file
cargo run -- call demo/v1/items/{id}/POST -p id=item_123 -d @payload.json

Configuration

Default home directory:

• ~/.apix
• override with APIX_HOME

Default registry remote:

• https://github.com/apix-sh/vault.git
• override with APIX_REGISTRY_URL

Auto-update controls:

• auto_update = true|false (default: true)
• auto_update_ttl_seconds = 21600 (6 hours, 0 disables time-based auto-update checks)
• APIX_AUTO_UPDATE overrides auto_update
• APIX_AUTO_UPDATE_TTL_SECONDS overrides auto_update_ttl_seconds

Default source priority:

• .local, core
• override with APIX_SOURCES (comma-separated), e.g. APIX_SOURCES=.local,core,acme

Default config file:

color = true
pager = ""
auto_update = true
auto_update_ttl_seconds = 21600
sources = [".local", "core"]

[registry]
remote = "https://github.com/apix-sh/vault.git"

[source.acme]
remote = "https://github.com/acme/apix-vaults.git"

Source Model

• Local builds are stored at ~/.apix/vaults/.local/<namespace>/<version>/...
• Core registry is stored at ~/.apix/vaults/core/<namespace>/<version>/...
• Third-party sources are stored at ~/.apix/vaults/<source>/<namespace>/<version>/...

Short route resolution order follows sources config (or APIX_SOURCES). If a short route exists in multiple sources, apix returns an ambiguity error and asks for --source or explicit source-prefixed route.

Search vs Grep

• search: Indexed API discovery across sources using registry.json (can include not-yet-pulled APIs)
• grep: Full-text markdown search within one namespace/source (content-level search)
• ls: Local inventory and route listing from local files

ls modes:

• apix ls: list namespaces grouped by source
• apix ls <namespace>: list versions for a namespace across sources
• apix ls <namespace>/<version>: list paths and methods with one-line route summaries
• apix ls <namespace>/<version>/<path...>: filter routes to those under the given path prefix
• Route-detail mode resolves from one source only: --source if provided, else first match by priority (.local -> core -> third-party)

Registry lifecycle:

• core/third-party sources: registry index comes from source root (registry.json) after update/pull
• .local source: registry index is auto-rebuilt after import
• Manual reindex:
  • local source: apix registry rebuild --source .local
  • vault repo path: apix registry rebuild --path /path/to/vault

Vault repo spec (for --path mode and source compatibility):

• docs/vault-repo-spec.md

Search auto-update:

• search can auto-refresh source registry.json before matching
• Auto-update uses registry-only fetch; it does not update pulled namespace content
• .local is excluded from auto-update and timestamp tracking
• Last successful source refresh timestamp: ~/.apix/vaults/<source>/.last-updated
• Skip once with apix search ... --no-auto-update

Output Behavior

• If stdout is a TTY: markdown is rendered for humans (termimad)
• If stdout is piped: raw markdown is emitted
• --raw forces raw markdown even in TTY mode
• --no-color or NO_COLOR=1 disables color styling
• show and ls <namespace>/<version> auto-page output in TTY mode using pager config / PAGER (fallback: less -FRX)
• --no-pager disables pager usage

Development

cargo fmt --all
cargo test --locked
cargo check --locked

Release Automation

Releases are automated with GitHub Actions + release-plz:

• .github/workflows/release-plz.yml:
  • opens/updates release PRs from commits on main
  • bumps Cargo.toml version and changelog
  • publishes crate + creates GitHub release after release PR merge
• .github/workflows/release.yml:
  • builds multi-platform binaries
  • uploads release tarballs and SHA256SUMS to the published GitHub release

Recommended commit style for clean changelogs:

• Conventional Commits (feat:, fix:, feat!:)