The plane CLI
Three commands — dev, keys, promote.
npx plane dev
npx plane keys create --name ci --scopes read,control
npx plane promote support-bot --to prodAll three need a key. --api-key or $PLANE_API_KEY, and the CLI refuses to start
without one, naming where a key comes from. The key is the environment your
laptop's agent and connection are written into, which is why a personal environment is
the intended target and why there is no --environment flag anywhere.
plane dev
Serves your app to a hosted Plane over an outbound socket. Full walkthrough: local development.
| Flag | Default | |
|---|---|---|
-c, --config <path> | plane.config.ts, then plane/agent.ts | the module exporting your definePlane result |
-n, --name <name> | your git user name | namespace: suffixes the agent slug and the connection |
--plane-url <url> | $PLANE_URL | the hosted Plane |
--api-key <key> | $PLANE_API_KEY | required |
--open | print the control-plane URL for your agent | |
--no-watch | do not re-sync when the definition changes | |
-q, --quiet | do not stream session events |
$PLANE_CONSOLE_URL overrides where the printed console link points; it defaults to
--plane-url.
plane keys create
npx plane keys create --name ci --scopes read,controlMints a key in the environment the calling key is in, at the scopes you name
(read,data by default — a runtime key, since a key that can rewrite an agent
definition should be asked for). The plaintext is printed once, alone on its line so
it can be piped, and never again.
On a fresh server the first key is printed to the log at boot. After that this command and the control plane's API keys page are the two ways to get one.
plane promote
PLANE_API_KEY=$PLANE_ORG_KEY npx plane promote support-bot --to prod
npx plane promote support-bot --to prod --map connection:orders=orders-prod --dry-runAlways runs a dry run first — the same server code path, writing nothing — and prints
the resolution, so a failure is legible in CI output. Nothing is written unless every
connection, provider and secret the definition names resolves in the target.
--map kind:from=to is repeatable; kind is connection, provider or secret.
An environment key cannot promote: a key is an environment and this crosses two. See promotion.