Configuration And Precedence

APKG resolves behavior from a small number of sources:

• Command-line flags for the current invocation
• Environment variables
• Persistent CLI configuration
• Built-in defaults

This page documents the precedence that is already described across the CLI reference.

File locations

APKG stores local state under ~/.apkg/.

File	Purpose
~/.apkg/config.json	Persistent CLI configuration set through apkg config
~/.apkg/credentials.json	Stored login credentials used by authenticated commands

Registry resolution

When APKG needs a registry URL, the documented precedence is:

1. --registry <URL> command-line flag
2. APKG_REGISTRY environment variable
3. registry value from apkg config
4. Default: https://api.apkg.ai

This order is stated in apkg login and applies to commands that talk to the registry.

Service overrides

The services.<name> configuration keys let you override specific backend services:

• services.auth
• services.package
• services.mfa
• services.search

When a service-specific override is not set, APKG falls back to the resolved registry URL.

Example:

apkg config set registry https://registry.internal.example.com
apkg config set services.auth http://localhost:8787

In that setup, auth requests use the explicit services.auth value while other registry-backed operations continue to use the registry URL.

Tool setup behavior

Automatic tool setup for skill and agent packages is controlled by a three-level precedence: explicit flags (--setup, --no-setup), persistent defaultSetup.<tool> config, and auto-detection of tool marker directories. See Tool Setup Explained for the full mechanism, detection rules, and generated file paths.

Documented tool keys are:

• defaultSetup.claude-code
• defaultSetup.cursor
• defaultSetup.windsurf
• defaultSetup.kiro
• defaultSetup.codex

Credentials

Login credentials are stored separately from general configuration in ~/.apkg/credentials.json.

Credentials are scoped to the resolved registry URL, so logging into one registry does not implicitly authenticate you against a different one.

Recommended usage

• Use command flags for one-off overrides.
• Use environment variables for ephemeral shell or CI configuration.
• Use apkg config for durable machine-level defaults.
• Keep registry selection explicit in automation when reproducibility matters.

Related pages

Page	Description
apkg config	Persistent CLI configuration keys
apkg login	Registry precedence and credential storage
Quick Start	Default tool setup in day-to-day usage