`box create`

Scaffold a new box project from the bundled template.

box create <name> [options]

Alias: box init <name>

Synopsis

box create generates a new project directory containing a starter box. It writes a box.json manifest and a .gitignore, then prints the next steps to authenticate and run the box.

Arguments

Argument	Required	Description
`<name>`	yes	The box name. Must match `^[a-z][a-z0-9-]*$` — lowercase letters, digits, and dashes, starting with a letter.

Options

Option	Description
`--control-plane <url>`	Control plane API URL for this box. Falls back to the `BOX_CONTROL_PLANE` environment variable when omitted. Stored as `controlPlaneUrl` in `box.json`.

Behavior

The target directory (named after <name>) must be empty; the command refuses to overwrite an existing project.
Files are copied from the CLI’s bundled template/ directory.
A box.json is written with name and, when provided, controlPlaneUrl.
A .gitignore is written that excludes node_modules/, dist/, .box/, .npmrc, .env, .env.local, nameserver.txt, and dns.txt.

After scaffolding, the CLI prints the suggested next steps:

cd <name>
box auth --org <org> --key <license>
box install
box start <name> 4000 3010

Examples

# Scaffold against the default control plane
box create acme-bank
 
# Scaffold against a specific control plane
box create acme-bank --control-plane https://control.example.com

The control-plane URL is resolved at command time in this order: explicit --control-plane flag → BOX_CONTROL_PLANE env var → box.json controlPlaneUrl. See resolution order.

box create