CLI reference

@commercit/app-cli supplies the commercit executable. The local V1 release uses an integrity-checked coordinated bundle; public npm publication remains a release gate. Follow Getting started to install the bundle and create a project. Inside a generated project, npm exec -- commercit <command> uses its locked CLI.

Command	Result
login --organization-id <uuid>	Browser device authorization for one explicit organization
logout	Revoke the saved interactive session and remove local credentials
status	Show the selected platform, organization and session expiry without a credential
init --name <slug> --template app-home --release-bundle <directory>	Install and scaffold an independent Astra App Home project
connect --organization-id <uuid> --app <slug> [--draft-id <uuid>]	Bind this project to one app and revisioned draft
connect --organization-id <uuid> --app <slug> --draft-id <uuid> --switch-draft	Explicitly select a successor draft in the same app while preserving project source
sync	Three-way configuration merge with explicit competing-edit failures
validate	Validate manifest, references, scopes and declared surfaces
build	Refresh canonical browser references and compile the local immutable artifact
dev	Synchronize, build, verify platform parity and watch development previews
test-api --session-id <uuid> --handler <ref> --input '{}'	Run one declared manual handler in a current scoped API development session
deploy	Synchronize and build an immutable candidate through the canonical platform builder
reconcile-build [--retry]	Read the recorded exact build; explicitly replay its saved upload only with --retry
reconcile-preview [--retry]	Read the recorded exact preview creation; explicitly replay the same request only with --retry
versions	Read the app’s immutable release history
submit [versionId]	Submit the connected draft’s current candidate, or an explicit version UUID
review [versionId]	Read review checks and findings for the selected candidate
publish [versionId] --confirm	Publish an approved immutable candidate through the existing lifecycle
generate	Generate reviewed source scaffolding from the existing prompt flow

Authentication

Interactive login follows the OAuth device authorization protocol. The browser shows the short user code, requested organization, expiry, Approve and Deny. The CLI alone holds the high-entropy device code; it is never placed in a URL or printed. Device requests expire after ten minutes. Polling starts at five seconds and slows down on server instruction. Denial, cancellation, expiry and reuse fail closed. Approved interactive tokens expire after eight hours; renewal requires a new explicit login and cannot switch project organization silently.

Saved credentials are outside the project at ~/.config/commercit/config.json, or under COMMERCIT_CONFIG_DIR. Restricted file permissions are applied where supported. They never enter draft configuration, source archives or console output.

CI uses an explicitly created automation token from the dashboard’s organization settings. Supply it through COMMERCIT_DEVELOPER_API_TOKEN. Existing release commands also retain their advanced --token option; prefer the environment to keep it out of shell history. The normal login command never asks for a reusable manual token.

--platform-url <origin> selects the platform. HTTPS is required outside loopback fixtures. Saved credentials cannot be forwarded to a different origin or through an HTTP redirect. COMMERCIT_PLATFORM_URL overrides the saved/default origin only when it remains compatible with the supplied credentials.

Init and connect

init supports app-home (default), extension (host components), connector (non-Astra managed worker) and the existing shipping carrier scaffold. --name must equal the app slug. Add --organization-id and --app together to authorize and connect the generated project immediately; --draft-id explicitly selects a matching existing draft. An existing directory is never overwritten.

The release bundle automatically supplies compatible CLI/compiler/contracts/SDK artifacts and their integrity bindings. Advanced complete artifact flags remain available: --sdk-artifact, --contracts-artifact, --cli-artifact and --compiler-artifact. Shipping retains --shipping-sdk-artifacts <manifest-path>. These advanced paths do not imply that unpublished packages are available publicly.

.commercit/project.json records organization, app, draft, project identity, base revision and base configuration. Unknown create/save outcomes retain their operation identity and use exact readback. Do not delete this metadata to bypass a conflict.

To select a successor created in the dashboard, stop dev, synchronize the current draft, then repeat connect with its new --draft-id and --switch-draft. Both drafts must belong to the same app and organization. Source files and unowned JSON values stay intact; owned manifest configuration adopts the selected draft. Dirty configuration, pending operations and an active development process block the switch. An interrupted selection resumes only through the same explicit command.

Sync and Astra

sync preserves unowned local values and files, merges disjoint edits and reports competing field paths without a partial write. Arrays such as scopes are atomic semantic declarations. Resolve conflicting local values against the dashboard and run synchronization again. JSON comments are unsupported; unknown manifest fields remain preserved but fail compiler validation.

dev and deploy also fetch the trusted Astra release selection into commercit.astra.json. Stable major follows the supported compatible channel. Exact pins never move automatically, including for security releases. Missing, revoked or incompatible pins require an explicit successor and a tested app release. The compiler validates the descriptor, public exports, SDK/API requirements and immutable source identity.

The canonical browser compiler refreshes each generated origin key and artifact reference from complete source/configuration identity. Repeating the refresh without changes is stable. Editing source creates a new immutable candidate; the app semantic version is not changed silently.

Build, preview and deployment

build writes .commercit/artifact/: the managed worker, reviewed browser assets, module graph, localization and immutable receipts. It uses the canonical compiler and package policy. No developer tunnel executes production-like traffic.

dev options:

Option	Purpose
--shop-id <uuid>	Choose an explicitly authorized development store
--target <target>	Choose a declared admin.app.home, theme or api target
--once	Build one preview and exit, leaving its bounded expiry in force
--no-browser	Print the non-secret preview URL without opening a browser
--platform-url <origin>	Select the authorized platform origin

Without --once, source and dashboard changes are watched. New previews are announced without remounting an open form. A failed build keeps the previous mounted artifact. Closing the CLI stops its loop and closes sessions it created. A canceled build cannot open a preview after completion. Expired or closed sessions require an explicit new dev run; a heartbeat cannot resurrect them.

App Home opens in the Admin Extension Host, themes use the existing customizer, and apps without a UI use their declared API validation session. API test commands accept only a declared manual handler with one operation and target; the canonical runtime validates input and preview authority. Provider network and secrets remain disabled.

deploy accepts --changelog <text> and --timeout <seconds> (default 1200). It synchronizes and builds locally, uploads the exact source/lockfile/manifest with draft_id and configuration_revision, and polls the accepted platform build. Completion must reproduce the local artifact digest. Stale revisions and superseded source builds cannot become the selected draft’s current candidate.

Before a build upload or preview creation, the CLI records the exact non-secret request in .commercit/pending-build.json or .commercit/preview-operation.json. A lost response triggers GET readback for that original identity, without another POST. Unknown operations block new uploads and configuration changes. Use reconcile-build or reconcile-preview after restarting; default reconciliation only reads. An accepted build whose phase remains queued may still need source storage or dispatch repair. After readback, reconcile-build --retry explicitly replays the saved upload with its original idempotency key, even if local source has since changed. This never rewrites local source or creates a new build identity. The preview equivalent reuses its recorded operation ID. A completed historical build still must satisfy current-draft eligibility before preview or submission.

Submit/review/publish default to that exact candidate. An explicit positional versionId is a UUID scoped to the same app and organization. Submission, review, merchant consent, publication and automatic rollout keep their existing authority.

Generate and environment

The existing generator accepts --section, --data-source, --action and --connector descriptions. It prints a prompt when no configured AI credential is available; with configured AI access it follows the existing generator provider path. Generated files still require validation, build and review. CLI login does not grant external AI/provider access.

Environment variable	Purpose
COMMERCIT_PLATFORM_URL	Selected developer API origin
COMMERCIT_DEVELOPER_API_TOKEN	Explicit CI automation credential
COMMERCIT_CONFIG_DIR	Auth configuration directory, outside source uploads
COMMERCIT_NPM_EXEC_PATH	Explicit npm CLI runtime path for local tooling/fixtures

Local proof does not authorize production deployment, package/app publication, remote database mutation, provider calls or merchant installation changes.