CLI Reference

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 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

  • --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#

APX API Path → Go Import Path

APX API Path

Go Module Path

Go Import Path

proto/payments/ledger/v1

github.com/<org>/apis/proto/payments/ledger

github.com/<org>/apis/proto/payments/ledger/v1

proto/users/profile/v1

github.com/<org>/apis/proto/users/profile

github.com/<org>/apis/proto/users/profile/v1

proto/inventory/products/v2

github.com/<org>/apis/proto/inventory/products/v2

github.com/<org>/apis/proto/inventory/products/v2

proto/billing/invoices/v1

github.com/<org>/apis/proto/billing/invoices

github.com/<org>/apis/proto/billing/invoices/v1

APX API Path → Python Package

APX API Path

Python Dist Name

Python Import Path

proto/payments/ledger/v1

<org>-payments-ledger-v1

<org>_apis.payments.ledger.v1

proto/users/profile/v1

<org>-users-profile-v1

<org>_apis.users.profile.v1

proto/orders/v1 (3-part)

<org>-orders-v1

<org>_apis.orders.v1

APX API Path → Java / Maven

APX API Path

Maven GroupId

Maven ArtifactId

Java Package

proto/payments/ledger/v1

com.<org>.apis

payments-ledger-v1-proto

com.<org>.apis.payments.ledger.v1

proto/users/profile/v1

com.<org>.apis

users-profile-v1-proto

com.<org>.apis.users.profile.v1

proto/orders/v1 (3-part)

com.<org>.apis

orders-v1-proto

com.<org>.apis.orders.v1

TypeScript — Planned. npm scope and package name derivation will follow the same deterministic pattern.

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

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.45.0
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#

Contents