Utility Commands

Utility Commands#

Commands for configuration management, toolchain setup, identity inspection, and workflow management.

apx config#

Manage the APX configuration file.

apx config init#

Create a default apx.yaml configuration file.

apx config init

Writes a default configuration using the canonical schema. Fails if apx.yaml already exists.

apx config validate#

Validate the configuration file against the APX schema.

apx config validate
apx config validate --config custom-apx.yaml
apx --json config validate

Returns a ValidationResult with errors and warnings. Exit code 6 indicates an invalid configuration.

Example output:

✔ Configuration is valid
  Warnings:
    - field "languages.python": language target not yet supported

apx config migrate#

Migrate a configuration file to the current schema version.

apx config migrate
apx --json config migrate

Creates a backup of the original file before migrating. Reports the from/to version and changes applied.

apx fetch#

Download and cache toolchain dependencies for offline use.

apx fetch

Flags#

Flag

Shorthand

Type

Default

Description

--config

-c

string

apx.yaml

Path to configuration file

--output

string

.apx-tools

Output directory for cached tools

--verify

bool

true

Verify checksums after download

What It Downloads#

Tools are resolved from apx.lock and cached in .apx-tools/:

.apx-tools/
├── buf                    # Buf CLI
├── protoc-gen-go          # Go protobuf plugin
└── protoc-gen-go-grpc     # Go gRPC plugin

Example#

# Download all pinned tools
apx fetch

# Verify checksums match apx.lock
apx fetch --verify

# Custom output directory
apx fetch --output /tmp/apx-tools

apx sync#

Synchronize go.work overlays with generated code directories.

apx sync

Flags#

Flag

Type

Default

Description

--clean

bool

false

Remove all overlays before syncing

--dry-run

bool

false

Show what would change without modifying files

What It Does#

Scans internal/gen/go/ for overlay directories and updates go.work with a use directive for each one:

go 1.22
use .
use ./internal/gen/go/proto/payments/ledger@v1.2.3
use ./internal/gen/go/proto/users/profile@v1.0.1

Examples#

# Sync after generating code
apx gen go && apx sync

# Preview changes
apx sync --dry-run

# Clean stale overlays and resync
apx sync --clean

apx inspect#

Inspect API identity, releases, and derived coordinates.

apx inspect identity#

Show the full canonical identity for an API.

apx inspect identity <api-id>

Flag

Type

Default

Description

--source-repo

string

from apx.yaml

Source repository

--lifecycle

string

""

Lifecycle state

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-corp/apis/proto/payments/ledger/v1
Go module:  github.com/acme-corp/apis/proto/payments/ledger
Go import:  github.com/acme-corp/apis/proto/payments/ledger/v1

apx inspect release#

Show identity for a specific API release.

apx inspect release <api-id>@<version>

Flag

Type

Default

Description

--source-repo

string

from apx.yaml

Source repository

Lifecycle is inferred from the version’s prerelease tag (alpha → experimental, beta/rc → beta, none → stable).

apx explain#

Explain how APX derives language-specific paths and coordinates.

apx explain go-path#

Explain Go module and import path derivation rules.

apx explain go-path <api-id>

Flag

Type

Default

Description

--source-repo

string

from apx.yaml

Source repository

Shows the derivation rules including Go’s v2+ major version suffix convention.

Example:

$ apx explain go-path proto/payments/ledger/v2
API ID:     proto/payments/ledger/v2
Go module:  github.com/acme-corp/apis/proto/payments/ledger/v2
Go import:  github.com/acme-corp/apis/proto/payments/ledger/v2

Derivation:
  v1 modules omit the version suffix: .../proto/payments/ledger
  v2+ modules include the suffix:     .../proto/payments/ledger/v2

Usage:
  go.mod:   require github.com/acme-corp/apis/proto/payments/ledger/v2 v2.0.0
  import:   import ledgerv2 "github.com/acme-corp/apis/proto/payments/ledger/v2"

apx workflows#

Manage GitHub Actions workflow files.

apx workflows sync#

Regenerate workflow files from the latest APX templates.

apx workflows sync
apx workflows sync --dry-run

Flag

Type

Default

Description

--dry-run

bool

false

Show what would be written without modifying files

Detects the repository type automatically:

Repository type

Detection method

Generated files

Canonical

ci.yml or on-merge.yml exists, or top-level proto//catalog/ dirs

ci.yml, on-merge.yml

App

apx-release.yml exists, or module_roots in config

apx-release.yml

Reads org and repo from apx.yaml (or falls back to git remote detection).

apx catalog#

Manage the API catalog in the canonical repository.

apx catalog generate#

Generate catalog.yaml from git tags in the canonical repo.

apx catalog generate

Flag

Shorthand

Type

Default

Description

--output

-o

string

catalog/catalog.yaml

Output path

--org

string

from apx.yaml

Organization name

--repo

string

from apx.yaml

Repository name

--dir

string

.

Git repository directory to scan

Scans git tags matching <format>/<domain>/<name>/<line>/v<semver> and generates a structured catalog. Typically run by on-merge.yml in the canonical repo.

See Also#

Contents