Skip to content

Core Commands

APX provides commands for managing API schemas across their full lifecycle.

apx init

Initialize a new APX project.

apx init [kind] [modulePath]   # Interactive or direct module init
apx init canonical             # Initialize canonical API repository
apx init app <modulePath>      # Initialize application repository

Common Flags

Flag Type Default Description
--non-interactive bool false Disable interactive prompts and use defaults
--org string auto-detected Organization name
--repo string auto-detected Repository name
--languages []string [go] Target languages (auto-detected from project files)

apx init canonical Flags

Flag Type Default Description
--org string Organization name
--repo string Repository name
--import-root string Custom public Go import prefix (e.g. go.acme.dev/apis)
--skip-git bool false Skip git initialization
--setup-github bool false Configure GitHub repo settings (branch/tag protection, org secrets) via gh CLI
--app-id string GitHub App ID for org secrets (used with --setup-github)
--app-pem-file string Path to GitHub App private key PEM file (used with --setup-github)

apx init app Flags

Flag Type Default Description
--org string Organization name
--repo string Repository name
--import-root string Custom public Go import prefix (e.g. go.acme.dev/apis)
--setup-github bool false Configure GitHub repo settings (branch protection) via gh CLI

apx gen

Generate code for the specified language.

apx gen <lang> [path]

Supported languages are listed dynamically; run apx gen --help to see them.

Flags

Flag Type Default Description
--out string Output directory
--clean bool false Clean output directory before generation
--manifest bool false Emit generation manifest

apx lint

Run linting checks on schema files.

apx lint <module-path>

apx breaking

Check for breaking changes between schema versions.

apx breaking <module-path>

apx inspect

Inspect API identity, releases, and derived coordinates. When a catalog is available (local or remote via catalog_url), inspect identity also shows latest versions, owners, and tags.

If import_root is set in apx.yaml, Go module and import paths use the custom root instead of the source repository path.

apx inspect identity <api-id>              # Show full API identity + catalog data
apx inspect release <api-id>@<version>     # Show identity for a release

Example:

$ apx inspect identity proto/payments/ledger/v1
API:        proto/payments/ledger/v1
Format:     proto
Domain:     payments
Name:       ledger
Line:       v1
Source:     github.com/acme/apis/proto/payments/ledger/v1
Go module:  github.com/acme/apis/proto/payments/ledger
Go import:  github.com/acme/apis/proto/payments/ledger/v1
Latest stable:      v1.2.3
Latest prerelease:  v1.3.0-beta.1
Owners:     @platform/payments
Tags:       public, core

apx search, apx show

See Dependency Commands for full flag tables and examples.

apx explain

See Utility Commands for full flag tables and examples.

apx config

Manage the APX configuration file.

apx config validate    # Validate apx.yaml against schema
apx config migrate     # Migrate to latest schema version

Configuration: import_root

By default, Go module and import paths are derived from the source repository (e.g. github.com/<org>/<repo>). Set import_root in apx.yaml to decouple the public Go import path from the hosting location:

# apx.yaml
org: acme
repo: apis
import_root: go.acme.dev/apis   # custom Go module prefix

With this configuration, apx inspect, apx show, apx explain go-path, and apx release all use the custom root:

Go module:  go.acme.dev/apis/proto/payments/ledger
Go import:  go.acme.dev/apis/proto/payments/ledger/v1

When import_root is omitted or empty, the source repository path is used as before, preserving full backward compatibility.