Box CLI

The Box CLI (@withpotter/box, invoked as box) is the command-line tool a vendor uses to authenticate a license, install the entitled engine, run the stack locally, and register the box’s public domains with the Potter control plane.

Authenticate your license and run your own Box (engine + console).

Install

The CLI ships as a standalone binary managed through the Potter Homebrew tap and GitHub releases.

Homebrew (macOS / Linux)

brew install withpotter/tap/box

Once installed, keep it current with the CLI’s own updater:

box upgrade            # upgrade to the latest release
box upgrade --check    # report the latest version without installing
box upgrade --version 0.1.0-alpha.10   # pin a specific version

box upgrade updates the CLI binary (installed at /opt/homebrew/bin/box on Apple Silicon). box update is different — it updates the entitled @withpotter/* engine packages inside a box. See box update and box upgrade.

Verify the install

box --version
box --help

Typical workflow

Create a box

box create acme-bank
cd acme-bank

Authenticate the license

box auth --org acme-bank --key <license-key>

Install the entitled engine

box install

Run the stack

box start acme-bank 4000 3010

Register public domains

box deploy --backend-url https://api.acme-bank.example

Follow the Quickstart for an end-to-end walkthrough.

Command summary

Command	Purpose
`box create <name>`	Scaffold a new box project (alias: `init`).
`box auth`	Activate a license, log in to the registry, compose entitlements.
`box install`	Install the entitled engine packages and dependencies.
`box update`	Update the entitled `@withpotter/*` engine packages.
`box start`	Run the engine and/or console locally.
`box brand`	Generate the console theme from `brand.json`.
`box deploy`	Register the box’s public domains with the control plane.
`box status`	Show the box’s activation state and entitlements.
`box upgrade`	Upgrade the CLI binary itself.

Global options

Option	Description
`-V, --version`	Print the CLI version and exit.
`-h, --help`	Print help for the CLI or any subcommand.

Next steps

Quickstart Configuration files Concepts

Introduction Quickstart