Skip to content

CLI Reference

Complete reference for all APX commands and options.

Command Categories

APX commands are organized into logical categories:

  • Core Commands

    • apx init - Initialize projects
    • apx fetch - Download toolchain
    • apx gen - Generate code with canonical imports
    • apx sync - Update go.work overlays
    • apx link - Link Python/TypeScript overlays for local dev
    • apx unlink - Remove overlays for released APIs

  • Dependencies

    • apx search - Discover APIs
    • apx show - View API details
    • apx add - Add dependencies

  • Releasing

    • apx release - Release pipeline (prepare, submit, finalize)
    • apx semver suggest - Suggest version bump

  • Validation

    • apx lint - Schema validation
    • apx breaking - Breaking changes
    • apx policy - Policy enforcement

  • Utilities

    • apx config - Configuration management
    • apx fetch - Download toolchain
    • apx inspect / apx explain - Identity analysis
    • apx external - External API management

  • Global Options

    • --verbose - Detailed output
    • --json - Machine-readable output
    • --quiet / --no-color - Output control
    • --config - Custom config file

Quick Reference

Most Common Commands

# Initialize new project (interactive)
apx init

# Add dependency
apx add proto/payments/ledger/v1@v1.2.3

# Validate schemas
apx lint && apx breaking --against=HEAD^

# Get version suggestion
apx semver suggest --against=HEAD^

# Generate code with canonical import paths
apx gen go       # generates stubs with canonical imports
apx sync         # updates go.work overlays

# Switch from overlay to released module
apx unlink proto/payments/ledger/v1
go get github.com/myorg/apis/proto/payments/ledger@v1.2.3

# Release pipeline (prepare -> submit -> finalize)
apx release prepare proto/payments/ledger/v1 --version v1.0.0
apx release submit
apx release finalize   # run by canonical CI

# Release history and inspection
apx release history proto/payments/ledger/v1
apx release inspect

# Lifecycle promotion
apx release promote proto/payments/ledger/v1 --to stable --version v1.0.0

Application code using canonical imports:

// service.go - your application
package service

import (
    // Pattern: github.com/<org>/apis/proto/<domain>/<api>/v1
    ledgerv1 "github.com/myorg/apis/proto/payments/ledger/v1"  
    usersv1 "github.com/myorg/apis/proto/users/profile/v1"
    productsv2 "github.com/myorg/apis/proto/inventory/products/v2"
)

type Service struct {
    ledgerClient   ledgerv1.LedgerServiceClient
    usersClient    usersv1.ProfileServiceClient
    productsClient productsv2.ProductServiceClient
}

Path Mapping Reference

Go Path Mappings

APX Path Target Coordinate Description
proto/payments/ledger/v1 github.com/<org>/apis/proto/payments/ledger Go module path (v0/v1: no suffix)
proto/payments/ledger/v2 github.com/<org>/apis/proto/payments/ledger/v2 Go module path (v2+: major suffix)

Cpp Path Mappings

APX Path Target Coordinate Description
proto/payments/ledger/v1 acme-payments-ledger-v1-proto Conan package reference

Java Path Mappings

APX Path Target Coordinate Description
proto/payments/ledger/v1 com.acme.apis:payments-ledger-v1-proto Maven coordinates (groupId:artifactId)

Python Path Mappings

APX Path Target Coordinate Description
proto/payments/ledger/v1 acme-payments-ledger-v1 Python distribution name

Rust Path Mappings

APX Path Target Coordinate Description
proto/payments/ledger/v1 acme-payments-ledger-v1-proto Cargo crate name

Typescript Path Mappings

APX Path Target Coordinate Description
proto/payments/ledger/v1 @acme/payments-ledger-v1-proto Scoped npm package name

Local Overlay Paths

APX API Path Local Generated Path Overlay in go.work
proto/payments/ledger/v1@v1.2.3 internal/gen/go/proto/payments/ledger@v1.2.3/ use ./internal/gen/go/proto/payments/ledger@v1.2.3
proto/users/profile/v1@v1.0.1 internal/gen/go/proto/users/profile@v1.0.1/ use ./internal/gen/go/proto/users/profile@v1.0.1 
# Search for APIs (single keyword or phrase)
apx search payments

# View full details for a specific API
apx show proto/payments/ledger/v1

# Add dependency
apx add proto/payments/ledger/v1@v1.2.3

Version Management

# Get version suggestion (requires --against)
apx semver suggest --against=HEAD^

Exit Codes

APX uses consistent exit codes:

  • 0: Success
  • 1: General error (command failed, validation error)
  • 6: Validation failure (lint or breaking-change check failed)

Environment Variables

APX_CONFIG

Override default configuration file location: 

export APX_CONFIG=/path/to/custom/apx.yaml
apx lint  # uses custom config

APX_VERBOSE

Enable verbose output for all commands: 

export APX_VERBOSE=true
apx lint  # now shows verbose diagnostics

Planned

APX_USE_CONTAINER and APX_CACHE_DIR environment variables are planned for a future release.

Configuration File

APX uses apx.yaml for configuration (generated by apx init):

version: 1                     # required
org: myorg                     # required
repo: my-apis                  # required
module_roots:                  # optional — schema root paths
  - proto
  - openapi
language_targets:
  go:
    enabled: true
policy:
  forbidden_proto_options:
    - "^gorm\\."
release:
  tag_format: "{subdir}/v{version}"
  ci_only: true
tools:
  buf:
    version: v1.66.1
execution:
  mode: "local"
  container_image: ""

Shell Completion

Enable shell completion for better CLI experience:

Bash

# Add to ~/.bashrc
source <(apx completion bash)

# Or install system-wide  
apx completion bash | sudo tee /etc/bash_completion.d/apx

Zsh

# Add to ~/.zshrc
source <(apx completion zsh)

# Or for oh-my-zsh
apx completion zsh > "${fpath[1]}/_apx"

Fish

apx completion fish | source

# Or install permanently
apx completion fish > ~/.config/fish/completions/apx.fish

Next Steps