`box auth`

Activate a license, authenticate to the package registry, and compose the box’s entitlements.

box auth --key <license-key> [--org <name>]

Synopsis

box auth is the command that turns a freshly scaffolded box into an authorized, runnable one. It exchanges your license key for a token and entitlement set, logs in to the entitled registry, and composes the engine and console from the packages your tier grants.

Options

Option	Required	Description
`--key <license-key>`	yes	Your Potter license key.
`--org <name>`	no	Organization name to associate with the activation.

Behavior

Activate the license

Calls the control plane POST /license/activate with { key, org? }. The control plane responds with the box’s tier, customerId, a JWT token, the entitled packages, a registryUrl, and an expiry.

Authenticate to the registry

Logs in to the entitled package registry using a derived username of the form box-<customerId> and writes a project-local .npmrc.

Persist license metadata and secrets

Writes the non-secret license block into box.json under license: { customerId, tier, registryUrl, packages, activatedAt }.
Writes secrets into .box/credentials.json (licenseKey, npmToken) with file mode 0600.

Compose entitlements

Composes the entitled engine packages into the engine module (engine.module.ts).
Projects the console’s page groups from the entitled @withpotter/pages-* packages and writes the resolved capability set into the console environment.

When finished, the CLI prints a summary of the activated tier and the capabilities your box now has.

⚠️

.box/credentials.json and .npmrc contain secrets and are git-ignored by the generated .gitignore. Never commit them. The license block in box.json is safe to commit — it contains no secrets.

Examples

# Activate with an organization name
box auth --org acme-bank --key pk_live_xxxxxxxx
 
# Minimal activation
box auth --key pk_live_xxxxxxxx

Deprecated alias: `box activate`

box activate <license-key>   # deprecated — use `box auth` instead

box activate is a hidden, deprecated alias for box auth. It prints a deprecation warning and forwards to the same flow. Prefer box auth.

box auth