CLI

The CLI currently ships only in the Shiplet source checkout. The repository package is private; it is not a public registry package. Do not invent an npm install shiplet or npx shiplet distribution.

If you do not already have authorized repository access, use Code Mode MCP or direct REST. The CLI is a contributor workflow, not the public onboarding path.

npm ci
npm run shiplet -- --help

Authenticate without leaking authority

Interactive commands use a short-lived browser authorization flow. Non-interactive read and write commands may receive an already-established least-privilege organization key through --token or SHIPLET_API_KEY from a secret store. Never put it in source, package content, browser code, logs, screenshots, or examples. The CLI rejects raw organization keys for deploy, promote, and rollback; those commands require trusted browser authorization.

The production default API origin is https://shiplet.cc. Use --api-url only for a trusted Shiplet origin; HTTPS is required except for an explicit loopback development origin.

Prepare without a network write

npm run shiplet -- prepare ./dist   --name "Checkout review"   --subdomain checkout-review   --visibility organization   --dry-run   --json

Inspect the normalized static package, visibility, and target origin. Remove --dry-run only when the preview is correct. Managed static preparation needs no Cloudflare connection.

Command flow

npm run shiplet -- prepare <path>
npm run shiplet -- fork <shiplet-id>
npm run shiplet -- pull <shiplet-id> <path> --draft <draft-id>
npm run shiplet -- diff <draft-id> <path> --version <draft-version>
npm run shiplet -- push <draft-id> <path> --version <draft-version>
npm run shiplet -- validate <draft-id> <path> --version <draft-version>
npm run shiplet -- promote <draft-id> --expected-active <revision-id> --approve
npm run shiplet -- deploy <revision-id> --target <target-id> --approve
npm run shiplet -- rollback <shiplet-id> --revision <revision-id> --expected-active <revision-id> --approve
npm run shiplet -- eject <shiplet-id> <path>

Use --json to preserve returned IDs, versions, digests, status, preview URL, and operation proof. diff is read-only. Successful validation does not activate a draft. Validation returns an authenticated preview URL bound to the exact Shiplet, draft, immutable revision, and draft version. Open it before promotion: the trusted host keeps artifact and widget code in opaque sandboxed frames. Preview keeps the active revision and active tenant unchanged. A changed draft invalidates the old preview.

Validate → preview → promote. The active review URL always represents the current active revision, not a draft preview.

Safety fences

• --version prevents concurrent draft overwrite.
• --expected-active rejects stale promotion or rollback.
• --approve records explicit intent. The shipped source-checkout CLI requires trusted browser authorization for deploy, promote, and rollback.
• Direct REST and core MCP may authorize a project-scoped agent to promote or roll back with shiplets:write and explicit approval; that does not change the CLI transport.
• Customer-owned deployment requires a trusted browser-authorized human session plus --approve.
• --idempotency-key safely retries an uncertain exact operation.
• --force replaces a non-empty pull/eject destination; it never bypasses server concurrency.

A failed validation or deployment leaves the prior active revision unchanged. A conflict requires pulling or inspecting current state before retrying.

Errors and uncertain outcomes

401 means authentication is missing or expired. 403 means the actor lacks the exact scope, project, or approval authority. 409 means a version, active revision, target, or idempotency intent conflicted. 422 reports package validation, 428 a missing approval or prerequisite, and 503 an unavailable isolated runtime or provider integration. None implies a partial successful mutation.

Deploy, promote, and rollback use a per-operation idempotency key. If a network timeout leaves the result uncertain, do not invent success and do not create a second intent. Reuse the exact reported --idempotency-key with the same inputs, or use --dry-run first to persist the bound request and key.

Condition	Safe recovery
Draft or active revision conflict	Pull or inspect the winning state, reconcile deliberately, and retry with its returned fence.
Required authorization or approval is denied or expires	Reauthenticate or obtain only the missing project scope. No protected effect is committed without its required approval.
Network response is lost	Reuse the exact reported idempotency key with identical inputs; never manufacture a second operation.
Offline	Local validation and publish dry-run still work. Network commands fail without claiming success.

Eject exports authored code and schema. Shiplet never injects kernel-owned credentials, grants, state, deployments, sessions, claims, or audit history, but validation does not secret-scan arbitrary authored files. Inspect package content for secrets before sharing it.

Next: read the full package contract, extension contract, and deployment prerequisites.