Publish With The Cloud CLI

Use the CLI path when you want copyable commands, CI-friendly deployment steps, or infrastructure automation. The flow is the same as Studio: verify locally, publish a package handoff, promote it, interact with the hosted runtime, and replay hosted evidence.

If this is your first publish and you want a guided UI, use the Studio path.

1. Verify The Local Package

Run from a JacqOS app directory:

jacqos verify

jacqos verify must pass before Cloud publish. A failed fixture, invariant, or redaction check blocks deployment locally; Cloud never receives an unverified package.

2. Sign In

jacqos cloud login \
  --management-url https://cloud.jacqos.io \
  --runtime-cell-url https://runtime.cloud.jacqos.io \
  --wait

If your account was issued an invite code, keep it in a JACQOS_ variable and pass it explicitly:

export JACQOS_CLOUD_INVITE_CODE="<invite-code>"

jacqos cloud login \
  --management-url https://cloud.jacqos.io \
  --runtime-cell-url https://runtime.cloud.jacqos.io \
  --invite-code "$JACQOS_CLOUD_INVITE_CODE" \
  --wait

The CLI stores session metadata under .jacqos/cloud/. It stores digests and scope metadata, not WorkOS provider secrets or runtime token plaintext.

Check account readiness:

jacqos cloud readiness --json

3. Select A Cloud Scope

Select or create the project, app, and environment you want to publish into:

jacqos cloud select \
  --project appointment-booking \
  --project-name "Appointment Booking" \
  --app appointment-booking \
  --app-name "Appointment Booking" \
  --environment prod \
  --environment-name "Production" \
  --json

The selected scope is organization-bound. If your WorkOS session belongs to a different organization, management writes fail before any runtime command is dispatched.

4. Deploy And Promote

jacqos verify
jacqos cloud deploy --json
jacqos cloud promote --json
jacqos cloud status --json

jacqos cloud deploy creates the verified package handoff. jacqos cloud promote makes that package the live evaluator for the selected app and environment. Shadow or failed packages cannot execute effects.

jacqos cloud status --json returns deployment summaries and usage metrics: health, lifecycle, request count, observation count, effect count, storage bytes, degraded/error counts, and last replay-export status. These are operational metrics, not canonical facts.

5. Operate The Deployment Lifecycle

Pause effect execution without deleting evidence:

jacqos cloud pause \
  --lineage lineage_first_user \
  --reason "operator maintenance" \
  --json

Rollback to an eligible prior package digest:

jacqos cloud rollback \
  --lineage lineage_first_user \
  --package-digest sha256:<previous-package-digest> \
  --reason "restore previous verified package" \
  --json

Archive a deployment record that should no longer appear in the normal active path:

jacqos cloud archive \
  --lineage lineage_first_user \
  --reason "superseded by production app" \
  --json

Pause, rollback, and archive are management lifecycle actions. They preserve audit receipts and hosted export evidence.

6. Issue A Scoped Runtime Token

Issue a token that can send observations and fetch hosted evidence:

jacqos cloud token issue \
  --scope observe \
  --scope export \
  --expires-in-seconds 2592000 \
  --json > runtime-token.json

export JACQOS_RUNTIME_TOKEN="$(jq -r .token runtime-token.json)"
export JACQOS_CLOUD_ENDPOINT="https://runtime.cloud.jacqos.io/v0/apps/appointment-booking/envs/prod"

The token value is returned once. Store it in your own secret store for your application. JacqOS persists token digests, scopes, expiry, and Cell Control receipts, not plaintext token material.

Rotate or revoke tokens explicitly:

jacqos cloud token rotate \
  --from-token-id runtime-prod-1 \
  --token-id runtime-prod-2 \
  --json

jacqos cloud token revoke \
  --token-id runtime-prod-2 \
  --reason "client rotated" \
  --json

7. Smoke-Test The Endpoint

jacqos cloud endpoint-smoke \
  --token-env JACQOS_RUNTIME_TOKEN \
  --json

This checks that the selected app and environment have a promoted evaluator and that the runtime token can reach the scoped runtime cell.

8. Send An Observation

Use the CLI:

jacqos cloud observe \
  --lineage lineage_first_user \
  --class appointment.requested \
  --payload-json '{"customer_id":"cust_123","requested_time":"2026-05-01T10:00:00Z"}' \
  --token-env JACQOS_RUNTIME_TOKEN \
  --json

Or call the public endpoint directly from your product:

curl --fail \
  -H "Authorization: Bearer $JACQOS_RUNTIME_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "lineage_id": "lineage_first_user",
    "class": "appointment.requested",
    "payload": {
      "customer_id": "cust_123",
      "requested_time": "2026-05-01T10:00:00Z"
    }
  }' \
  "$JACQOS_CLOUD_ENDPOINT/observe"

Runtime tokens are checked against the app id, environment id, operation scope, expiry, and revocation state. Missing, invalid, revoked, or wrong-scope tokens are rejected before observations are appended.

When Studio appends to the same hosted lineage, it uses the selected cloud work view, requires the cloud append warning, evaluates the declared write policy, checks package identity, and refuses stale hosted projections.

9. Export And Replay Hosted Evidence

Fetch hosted evidence and validate the local round trip:

jacqos cloud replay-export \
  --lineage lineage_first_user \
  --token-env JACQOS_RUNTIME_TOKEN \
  --output hosted-export.json \
  --json

The export includes evaluator identity, package identity, mapper-output digests, redacted observations, hosted facts, intents, effects, and provenance. Replay must recompute the same semantic identities. If package, evaluator, or mapper-output digests drift, treat the export as failed evidence rather than a successful proof.

Use jacqos cloud export --json when you need the hosted evidence receipt without the local replay handoff.

Command And API Reference

Need	CLI	API surface
Sign in	jacqos cloud login	WorkOS-backed management auth
Select scope	jacqos cloud select	Project/app/environment management records
Publish package	jacqos cloud deploy	POST /api/v0/deployments
Promote package	jacqos cloud promote	Cell Control activation handoff
Pause effects	jacqos cloud pause	POST /api/v0/deployments/lifecycle
Rollback activation	jacqos cloud rollback	POST /api/v0/ops/rollback
Archive deployment	jacqos cloud archive	POST /api/v0/deployments/lifecycle
Health and metrics	jacqos cloud status	GET /api/v0/health plus deployment summaries
Issue token	jacqos cloud token issue	POST /api/v0/tokens/runtime
Rotate token	jacqos cloud token rotate	POST /api/v0/tokens/runtime/rotate
Revoke token	jacqos cloud token revoke	POST /api/v0/tokens/runtime/revoke
Append observation	jacqos cloud observe	POST /v0/apps/<app-id>/envs/<environment-id>/observe
Export evidence	jacqos cloud replay-export	GET /v0/apps/<app-id>/envs/<environment-id>/export?lineage_id=<lineage-id>

Next Steps

• Publish with Studio if someone on the team wants the visual Cloud panel and hosted provenance workflow.
• Cloud Troubleshooting and Security for failure ids, token boundaries, lifecycle states, and support-safe data handling.
• CLI Reference for the full command surface.