CLI

Every storefront workflow (scaffold, develop, deploy) runs through the Cimplify CLI.

Install

curl -fsSL https://cimplify.io/install | sh

Detects your OS + arch, downloads the matching binary from the latest GitHub release, verifies its sha256, and drops it in ~/.local/bin/cimplify. Cold start ≈ 20 ms. The binary bundles every template and the full component registry, so init, add, and list work the same as deploy, logs, env, and the rest, with no separate @cimplify/sdk install required.

Pin a version or change the install location:

curl -fsSL https://cimplify.io/install | sh -s -- --version cli-v0.1.0
curl -fsSL https://cimplify.io/install | sh -s -- --prefix ~/.cimplify

Need to run it once without installing? bunx @cimplify/cli <command> (or npx, pnpm dlx) works too; slower cold start, same behavior.

Zero to production

For the scannable ten-command flow, see the TL;DR. The rest of this page is the per-subcommand reference.

Subcommand index

Scaffold & develop

Command	What it does
`cimplify init`	Scaffold a Next.js storefront from one of six templates.
`cimplify add` / `cimplify list`	Eject one of 67 registry components into your project.
`cimplify dev [--remote]`	Run your project's dev script (optionally with prod env).
`cimplify-mock`	Boot the local mock API on `:8787`. Ships with `@cimplify/sdk`.

Auth

Command	What it does
`cimplify login`	Browser-first OAuth Authorization Code + PKCE on a loopback redirect. `--api-key` is the CI escape hatch.
`cimplify logout`	Forget saved credentials.
`cimplify whoami`	Show the current account and business.

Projects & deploys

Command	What it does
`cimplify projects ls`	List projects in the current business.
`cimplify projects create <name>`	Create a new Next.js project.
`cimplify link <project-id>`	Link CWD to a Cimplify project (writes `.cimplify/project.json`).
`cimplify unlink`	Remove the local project link.
`cimplify repo provision / connect / info`	Attach a managed or external git repo to the project.
`cimplify deploy`	Push current SHA + trigger a build (preview by default; `--prod` for production).
`cimplify rollback <deploy-id>`	Re-deploy a previous deployment's SHA.
`cimplify status`	Show the latest deployment for the linked project.
`cimplify logs [--follow]`	Stream build logs.

Env & domains

Command	What it does
`cimplify env ls / pull / push / add / rm`	Manage env vars per scope: `development \| preview \| production`.
`cimplify domains ls / add / verify / rm / attach / detach / primary`	Manage business-scoped domains; attach to projects per env.

Agent helpers

Command	What it does
`cimplify introspect`	One-shot snapshot of the current storefront: auth, link, brand, mock seed, env keys, git. Pure local; no API calls.
`cimplify inspect`	Read-only snapshot of the storefront's catalogue + merchandising state via the public key. Designed for agents (`--json`).
`cimplify doctor [--offline]`	14 pre-flight checks with verdicts and fix hints. Exits `1` on any `fail`.
`cimplify explain [topic]`	Print canonical guidance offline (cart, products, bundles, composites, errors, …). 20 bundled topics.

Storefront assets

Command	What it does
`cimplify assets upload <dir>`	Upload brand/storefront images to the Cimplify CDN; writes `cimplify-assets.json`; idempotent by SHA-256.
`cimplify assets ls`	List manifest entries with their stable CDN URLs.
`cimplify assets rm <key>`	Remove a manifest entry (manifest-only; remote blob stays in v1).

Global flags for agents and CI

Two global flags apply to every cloud subcommand and let scripts (or LLM agents) drive the CLI deterministically.

Flag	Equivalent env	What it does
`--json`	`CIMPLIFY_JSON=1`	Emit a single JSON envelope on stdout instead of colorized progress. Success: `{ "ok": true, "data": ... }`. Failure: `{ "ok": false, "error": { "code", "message", "remediation"? } }`. All human chatter (`step`, `success`, `info`) is suppressed; the envelope is the agent's only parse target.
`--yes`, `-y`	`CIMPLIFY_YES=1`	Auto-confirm every yes/no prompt. Without it, a non-TTY run that needs confirmation throws `INTERACTIVE_REQUIRED` rather than guessing.

Agent-driven flow

# Headless CI auth
cimplify login --api-key dk_live_xxx --json

# Capture latest deployment state
DEPLOY=$(cimplify status --json)

# Trigger and wait, parsing JSON outcome
cimplify deploy --prod --yes --json

Sample JSON envelopes

# Success
{"ok":true,"data":{"deployment":{"id":"dep_01H…","git_sha":"abc…","environment":"production","status":"active","url":"https://…"}}}

# Failure
{"ok":false,"error":{"code":"NOT_LINKED","message":"no linked project in this directory","remediation":"run `cimplify link <project-id>`"}}

In --json mode the browser PKCE login path refuses (interactive); use --api-key to authenticate non-interactively.

Exit codes

Distinct per error class so callers can branch on $? without parsing output:

Code	Name	Meaning
`0`	OK	Success. For `deploy`, deployment is `active`.
`1`	FAILED	Generic failure (build failed, deploy errored).
`2`	SUPERSEDED	A newer push raced this deploy; usually fine.
`3`	ABORTED	User canceled (Ctrl-C) or `cimplify_cancel_deployment`.
`4`	NOT_LINKED	`.cimplify/project.json` missing. Run `cimplify link <id>`.
`7`	INTERACTIVE_REQUIRED	A prompt was needed but `--yes` not passed and stdin is non-TTY.
`9`	NOT_FOUND	Resource (project, domain, deploy) does not exist.
`10`	NETWORK_ERROR	Could not reach `api.cimplify.io`.
`12`	TIMEOUT	Long-poll exceeded its window; the underlying job may still be running.
`20`	NOT_LOGGED_IN	No saved token. Run `cimplify login` or pass `--api-key`.
`21`	AUTH_FAILED	Token expired or revoked. Re-login.
`30`	INVALID_INPUT	Argument/flag validation failed.

Full list in @cimplify/cli/errors.

Mock API

The mock storefront API ships in @cimplify/sdk because it's tightly coupled to the SDK's domain types and seed data. Once the SDK is installed in your project, boot it with bunx @cimplify/sdk mock (or the cimplify-mock bin directly). Full surface in the mock reference.

Where next

init: scaffold a storefront Six templates, working in 60 seconds.
login: browser-first OAuth PKCE on a loopback redirect.
deploy: push and ship Preview, prod, rollback, logs.
mock: local API Eight seeds, frozen clocks, webhooks.

CLI

On this page