Operator Guide

Overview

Workflow Studio CLI provides the operator-facing workflows for deployment lifecycle, run control, and ownership validation.

Use the top-level commands for normal operations. The workflow-studio compute ... subcommands remain available as lower-level packaging and validation helpers.

Recommended operator flows

Deploy and activate the latest build

npx workflow build
npx workflow-studio deploy \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"

This command validates the generated workflow bundles, packages .well-known/workflow/v1/{flow.js,step.js,webhook.js} plus manifest metadata, uploads the archive, activates the uploaded deployment, and prints the deploymentId.

Roll back to a previous deployment

npx workflow-studio rollback \
  --deployment-id <deploymentId> \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"

Rollback is implemented as deployment activation. It switches the active deployment pointer without rebuilding or reuploading artifacts.

Split packaging from upload when needed

npx workflow build
npx workflow-studio compute build
npx workflow-studio compute deploy \
  --artifact .workflow-studio/dist/artifact.tgz \
  --manifest .workflow-studio/tmp/<deploymentId>/manifest.json \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"
npx workflow-studio compute activate \
  --deployment-id <deploymentId> \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"

Worker commands

Validate worker configuration

npx workflow-studio worker check-config

Exit codes:

• 0 - valid configuration
• 2 - valid with warnings
• 1 - invalid configuration

Start worker

npx workflow-studio worker start

Optional flags:

npx workflow-studio worker start \
  --config ./workflow.config.ts \
  --port 3001 \
  --host 0.0.0.0 \
  --require-https true

Lower-level deployment artifact commands

These commands expose the individual build, upload, and activation stages.

Build deployment artifact

npx workflow-studio compute build

Outputs the generated deployment ID and manifest path to stdout:

Built artifact: .workflow-studio/dist/artifact.tgz
Deployment ID: dep_abc123...
Manifest: .workflow-studio/tmp/dep_abc123.../manifest.json

Deploy artifact

npx workflow-studio compute deploy \
  --artifact .workflow-studio/dist/artifact.tgz \
  --manifest .workflow-studio/tmp/<deploymentId>/manifest.json \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"

Activate deployment

npx workflow-studio compute activate \
  --deployment-id <deploymentId> \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"

Roll back deployment

npx workflow-studio compute rollback \
  --deployment-id <deploymentId> \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"

Validate remote ownership

npx workflow-studio compute validate-ownership \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY" \
  --strict \
  --app-url "https://your-app.example.com"

Optional:

• --config ./workflow.config.ts to load typed remoteWorldTarget from config.

Checks performed:

• worker health endpoint is reachable
• active deployment exists

Strict validation

npx workflow-studio compute validate-ownership \
  --url https://worker.example.com \
  --app-url https://app.example.com \
  --strict

Additional strict checks:

• app diagnostics endpoint is reachable
• app runtime target world matches expected remote target
• diagnostics ownership status is not fail

Production diagnostics authentication

npx workflow-studio compute validate-ownership \
  --url https://worker.example.com \
  --app-url https://app.example.com \
  --strict \
  --diagnostics-token "$WORKFLOW_STUDIO_DIAGNOSTICS_TOKEN"

Common failures

No active deployment

Output includes an active deployment failure.

Action:

• run workflow-studio rollback --deployment-id <id> ... or call POST /v1/deployments/:id/activate

Target world mismatch

App runtime target world does not match expected remote target.

Action:

• set WORKFLOW_TARGET_WORLD=workflow-studio/world-remote on the application deployment.

Diagnostics endpoint unavailable

App diagnostics endpoint cannot be reached.

Action:

• verify route registration
• verify auth token configuration
• rerun with correct --app-url

CI usage

- name: Validate Remote Ownership
  run: |
    npx workflow-studio compute validate-ownership \
      --url "$WORKFLOW_COMPUTE_BASE_URL" \
      --app-url "$APP_URL" \
      --strict
  env:
    WORKFLOW_COMPUTE_BASE_URL: ${{ secrets.WORKFLOW_COMPUTE_BASE_URL }}
    APP_URL: ${{ vars.APP_URL }}

Operator API workflows

The worker also exposes API-key-scoped operator endpoints for automation and dashboards.

Deployments

• POST /v1/deployments creates a deployment from uploaded manifest and artifact data.
• POST /v1/deployments/:id/activate activates a deployment.
• GET /v1/deployments/:id reads deployment metadata.
• GET /v1/deployments/active reads the active deployment pointer.

Run control

• POST /v1/runs triggers a run and requires an Idempotency-Key header.
• POST /v1/runs/:id/cancel cancels a run.
• POST /v1/runs/resume resumes a run.
• POST /v1/runs/:id/rerun re-enqueues the run against the selected deployment.
• POST /v1/runs/:id/wake emits valid wait_completed events for matching waits.

Observability

• GET /v1/runs/:id
• GET /v1/runs/:id/steps
• GET /v1/runs/:id/hooks
• GET /v1/steps/:id
• GET /v1/hooks/:id
• GET /v1/events
• GET /v1/events/correlation/:id

See Observability for query patterns and resolveData defaults.

Queue behavior in v1

Queue behavior stays intentionally narrow in v1. There is no separate worker-owned queue settings API yet.

Operator queue control happens through run actions:

• resume for paused runs,
• rerun to enqueue a fresh execution path for an existing run,
• wake to complete waits that are ready to resume,
• cancel to stop in-flight work.

The raw POST /v1/queue/publish path exists only for internal world-remote traffic and is not a general public operator API.

Exit codes

worker check-config

• 0 - valid configuration
• 2 - valid with warnings
• 1 - invalid configuration

compute validate-ownership

• 0 - all checks passed
• 2 - warnings only
• 1 - hard failure

Typical rollout sequence

1. npx workflow-studio worker check-config
2. npx workflow-studio worker start
3. npx workflow build
4. npx workflow-studio deploy
5. npx workflow-studio compute validate-ownership --strict