Configuration

There are two configuration surfaces. The CLI reads a small config directory on each machine. A self-hosted registry is configured entirely through environment variables. This page covers both, grounded in the example environment file the repository ships.

The CLI config directory

The CLI keeps its settings in a config directory — the .skillhub folder, present in two scopes: a project-scoped copy at the repository root and a machine-global copy under your home directory. Settings resolve project-first, then global, then built-in defaults.

The settable keys — including registryUrl, the self-host seam — are documented on the config page. Credentials are stored separately from config: the CLI prefers your OS keychain and falls back to a private-mode file. See API tokens for how credentials are issued and used.

The environment-variable prefix

Every registry environment variable shares one product prefix: SKILLHUB_. Runtime code never hardcodes it — the prefix is owned by the branding seam and every variable name is built from a single helper, so a product rename changes the prefix in one place. That's why the variables on this page are written SKILLHUB_-prefixed. The example environment file in the repository lists every variable by its full literal name with a working local default; copying it to your own .env is the intended starting point.

The registry-URL override

The single most important setting for pointing the CLI at a registry you run is the registry-URL override. It resolves in order of precedence:

1. The --registry-url command-line flag.
2. The registry-URL environment variable (SKILLHUB_REGISTRY_URL).
3. The registryUrl project config key.
4. The registryUrl global config key.
5. The built-in default.

Setting the environment variable lets a whole shell or CI job target your registry with no stored config. The config-key routes are described on the config page.

Database

The registry reads its Postgres connection from a single DSN:

• SKILLHUB_DATABASE_URL — the full Postgres connection string. Override it to point at a remote database without touching anything else.

The example environment file also breaks the connection into individual parts (user, password, database name, port) that the local Compose stack reads to bring up its own Postgres.

Storage

Skill archives live in an S3-compatible bucket. Storage runs in one of two modes, selected by the SKILLHUB_STORAGE variable:

Auth mode

Authentication runs behind an adapter selected at boot:

• SKILLHUB_AUTH=stub — the default developer mode. It uses deterministic seeded identities and a local sign-in page, so no external auth project is required.
• SKILLHUB_AUTH=supabase — the hosted auth adapter, which requires its own URL and key variables to be set.

Other server variables

• SKILLHUB_PORT — the HTTP port the reference server listens on.
• SKILLHUB_SCANNER — rules (the default — the shared rule-pack scanner, so a local publish is scanned exactly as a production one is) or permissive (an always-pass engine for local publish loops).
• SKILLHUB_BILLING — off for a self-hosted registry; the hosted billing provider is not part of a self-host build.

Where to go next