CLI Overview

Open source at https://github.com/CloudCruise/cloudcruise-cli. Report bugs via GitHub issues or Discord. The CloudCruise CLI provides a command-line interface for managing workflows, workflow components, runs, vault credentials, and builder agent sessions. It’s designed for coding agents to build, diagnose, fix, and verify workflows, but works just as well for manual use. All output is JSON on stdout; errors go to stderr.

Installation

npm install -g @cloudcruise/cli

Or run without installing:

npx @cloudcruise/cli --help

Setup

cloudcruise login

After you sign in, tokens are saved to your OS keychain. If your account requires MFA, the CLI prompts for a TOTP code (or pass --mfa-code for non-interactive login). Use --no-open to print the login URL instead of opening a browser. Then select the workspace you want to use:

cloudcruise workspaces list
cloudcruise workspaces use <workspace_id>

Profiles

Each login is saved to a named profile, so you can keep separate credentials for different environments or accounts:

cloudcruise login --profile staging
cloudcruise auth profiles             # List profiles
cloudcruise auth switch staging       # Set the active profile
cloudcruise whoami --profile staging  # Check a specific profile

Every command accepts --profile <name> and --workspace-id <id> to override the active profile and workspace for a single call.

CI and Non-Interactive Use

For CI or other environments without a browser, set CLOUDCRUISE_TOKEN. It takes precedence over any saved profile. Legacy API keys are still supported. Pass one via stdin, or set the CLOUDCRUISE_API_KEY environment variable:

echo "sk_..." | cloudcruise auth login --api-key-stdin

Environment Variables

Variable	Description
`CLOUDCRUISE_TOKEN`	Bearer token for CI and non-interactive use (overrides saved profiles)
`CLOUDCRUISE_API_KEY`	Legacy API key
`CLOUDCRUISE_PROFILE`	Auth profile to use
`CLOUDCRUISE_WORKSPACE_ID`	Workspace to use (overrides the profile’s active workspace)
`CLOUDCRUISE_ENCRYPTION_KEY`	Hex-encoded AES-256 key for vault operations that encrypt or decrypt credentials
`CLOUDCRUISE_BASE_URL`	API base URL
`CLOUDCRUISE_CONVERSATION`	Default builder conversation ID for `builder` commands
`CLOUDCRUISE_SKILLS_AUTO_UPDATE`	`0` or `1`: turn skills auto-refresh off or on (overrides `settings.skillsAutoUpdate`)

Secrets passed as command-line flags (--api-key, --encryption-key, --value) are rejected by default because they leak into shell history and ps output. Use the matching --*-stdin flag or an environment variable instead.

Coding Agent Integration

Claude Code: install the plugin from the CLI repo’s marketplace. This registers the CloudCruise skills (workflow build, test, debug, CLI and DSL reference) and keeps them updated with /plugin update cloudcruise:

/plugin marketplace add CloudCruise/cloudcruise-cli
/plugin install cloudcruise@cloudcruise

Other agents (Cursor, Codex, Devin, or Claude Code without plugins): install the skill files into your project:

cloudcruise install --skills                   # All targets (default)
cloudcruise install --skills --target claude   # .claude/skills/
cloudcruise install --skills --target cursor   # .cursor/skills/
cloudcruise install --skills --target codex    # .agents/skills/ (also used by devin, agents)

This copies a CLI usage reference and a complete workflow DSL reference (all node types, XPath best practices, variables, JSONata, error classification) into your project where the agent can discover them.

Staying Up to Date

CLI: the CLI tells you, and your coding agent, when a newer version exists. Update with npm i -g @cloudcruise/cli@latest. CI and NO_UPDATE_NOTIFIER turn the check off.
Skills: after a CLI upgrade, the next command refreshes the skills that cloudcruise install --skills wrote into the current project. Skills you edited are left alone; cloudcruise install --skills overwrites them. Plugin-installed skills update with the plugin.

To turn off the skills refresh, set this in ~/.cloudcruise/config.json:

{ "settings": { "skillsAutoUpdate": false } }

CLOUDCRUISE_SKILLS_AUTO_UPDATE=0 or =1 overrides the setting. With the refresh off, the CLI warns about outdated skills instead.

Quick Start

cloudcruise workflows list
cloudcruise workflows get <workflow_id> > workflow.json

cloudcruise run start <workflow_id>
cloudcruise run get <session_id>   # poll until the run's status is final (see [Run Statuses](/concepts/run-statuses))

cloudcruise workflows update <workflow_id> --file workflow.json --version-note "Fixed selector"

Run Options

cloudcruise run start <workflow_id> --input '{"USER":"f47ac10b-..."}'  # Input variables
cloudcruise run start <workflow_id> --debug                            # Snapshot every node
cloudcruise run start <workflow_id> --dry-run                          # Stop at the end_here_on_dry_run node
cloudcruise run start <workflow_id> --no-notifications                 # No Slack/email notifications for this run
cloudcruise run start <workflow_id> --version "^2.1.0"                 # Highest release matching a version or range
cloudcruise run start <workflow_id> --branch fix-login                 # Latest version on a branch (name or id)

--dry-run ends the run at the node marked end_here_on_dry_run. Nodes before it still run, and a workflow without the marker runs in full. To check a payload before starting a run, validate it against the workflow’s saved input schema:

cloudcruise workflows validate-input <workflow_id> --file payload.json

It exits 0 if the payload is valid, 1 if it’s invalid (per-field errors in errors), and 2 if the workflow’s input schema itself doesn’t compile. Validation runs against the saved schema, so push schema edits with workflows update first.

Error-Fix-Verify Loop

You can use the CLI to fix existing workflow errors. Here’s how a coding agent could sequence CLI commands:

# 1. Diagnose: inspect the failed run and recent errors
cloudcruise run get <session_id>
cloudcruise run errors <workflow_id> --since 7d
cloudcruise workflows get <workflow_id> > workflow.json

# 2. Reproduce: re-run with debug snapshots
cloudcruise run start <workflow_id> --input '{}' --debug
# run start returns { session_id } immediately; note the new session_id
# and poll run get until its status is terminal.
cloudcruise run get <new_session_id>

# 3. Inspect: download the snapshot and find a working selector
cloudcruise snapshot fetch <new_session_id> <node_id>
cloudcruise snapshot suggest <new_session_id> <node_id>
cloudcruise snapshot test "//button[@type='submit']" <new_session_id> <node_id>

# 4. Fix: edit the workflow, then push the update
cloudcruise workflows update <workflow_id> --file workflow.json --version-note "Fixed XPath"

# 5. Verify: confirm the fix
cloudcruise run start <workflow_id> --input '{}'
cloudcruise run get <new_session_id>   # poll until the run's status is final (see [Run Statuses](/concepts/run-statuses))

The --debug flag forces every node to capture a page snapshot, which is essential for diagnosing selector issues. Without it, failed runs often lack snapshots.

Debugging with Snapshots

After a --debug run, the snapshot commands let you work with a node’s captured page:

# Download the HTML snapshot, screenshots, and metadata (default: ./snapshots)
cloudcruise snapshot fetch <session_id> <node_id>
cloudcruise snapshot fetch <session_id> <node_id> --html --output-dir ./debug

# Suggest unique XPath selectors for interactive elements
cloudcruise snapshot suggest <session_id> <node_id>
cloudcruise snapshot suggest <session_id> <node_id> --filter input,button

# Test an XPath selector and show the matched elements
cloudcruise snapshot test "//input[@name='email']" <session_id> <node_id>
cloudcruise snapshot test "//input[@name='email']" <session_id> <node_id> --count

# Work with a local HTML file instead of fetching from the API
cloudcruise snapshot suggest --file ./snapshots/page.html
cloudcruise snapshot test "//input[@name='email']" --file ./snapshots/page.html

run snapshots <session_id> <node_id> returns the raw snapshot metadata without downloading anything.

Watching a Live Session

cloudcruise run live-view <session_id>

Returns a viewer URL and its auth token. The token is single-use: if the viewer link was already opened (reloaded, or reopened later), it fails to connect. Run the command again to mint a fresh token and link. Only works while the session is still active.

Responding to User Interaction

When a run is waiting on a User Interaction node, submit the data it expects with run respond. The body is a JSON object matching the node’s expected_datamodel, passed via exactly one of --data, --file, or --stdin:

cloudcruise run respond <session_id> --data '{"approval_code":"123456"}'
cloudcruise run respond <session_id> --file interaction.json

Builder Agent

The builder commands drive the Builder Agent from the terminal, so a coding agent can build a new workflow or edit an existing one.

# Start a new build (or edit an existing workflow)
cloudcruise builder start --start-url "https://app.example.com" --name "Download invoices" \
  --vault-user-id acme-prod --vault-domain "https://app.example.com"
cloudcruise builder edit --workflow <workflow_id> --use-example-inputs
cloudcruise builder edit --workflow <workflow_id> --branch fix-login   # Edit a branch; saves go to it

# Send an instruction, then wait for the turn to finish
cloudcruise builder send "Log in and open the invoices page"
cloudcruise builder await-turn

# If the agent asks for input, answer it
cloudcruise builder status
printf '%s' 'my answer' | cloudcruise builder respond --message-id <message_id> --value-stdin

# Inspect progress
cloudcruise builder workflow                 # Current workflow definition
cloudcruise builder screenshot --output page.png
cloudcruise builder html --output page.html
cloudcruise builder messages --limit 20

# Save and finish
cloudcruise builder save -m "Initial invoice download flow"
cloudcruise builder end

builder send returns as soon as the agent accepts the message. builder await-turn blocks until the turn settles, and builder status reports the current state. Both encode the result in the exit code so a script can branch without parsing stdout:

Exit code	`await-turn`	`status`
`0`	Turn completed; stdout is the agent’s report	Completed, idle, or ended
`7`	Awaiting human input; answer with `builder respond`	Awaiting human input
`8`	Agent errored	Agent errored
`9`	Timed out while still processing (raise `--timeout-seconds` or re-run)	Still processing

Commands target the workspace’s current conversation by default. Pass --conversation <id> (or set CLOUDCRUISE_CONVERSATION) to target a specific one. builder conversations list shows live conversations, and builder conversations get <id> fetches an archived transcript.

Branches and Pull Requests

Workflow branches and pull requests work like git and gh pr. Branches are named by name or id, pull requests by number (12, #12) or id, and every command takes --workflow <workflow_id>.

cloudcruise branches create fix-login --workflow <workflow_id>
cloudcruise workflows get <workflow_id> --branch fix-login > workflow.json
cloudcruise workflows update <workflow_id> --file workflow.json --branch fix-login --version-note "Fix login XPath"
cloudcruise run start <workflow_id> --branch fix-login
cloudcruise prs create --workflow <workflow_id> --head fix-login --title "Fix login XPath"
cloudcruise prs approve 12 --workflow <workflow_id>      # By another workspace member
cloudcruise prs merge 12 --workflow <workflow_id>

Merging with Conflicts

When both branches changed the same item differently, prs merge exits 14 (MERGE_CONFLICTS) and names each conflict. prs diff shows each one with a key, a one-line summary and the base, source and target values, plus the match_heads to merge against:

cloudcruise prs diff 12 --workflow <workflow_id>
cloudcruise prs merge 12 --workflow <workflow_id> --match-heads <match_heads> \
  --resolve nodes:<node_id>=target --take source

--resolve <key>=source|target|delete answers one conflict, --take source|target answers the rest, and --resolutions-file sets custom values (prs diff --resolutions-template writes a file to start from). If either branch changed since the diff, nothing is merged and the command exits 13; run prs diff again. To resolve conflicts and test the result before merging, merge the base into your branch first, as in git: open a pull request from the base into your branch (--head main --base fix-login), merge it with resolutions, test your branch with run start --branch, then merge your branch. It no longer conflicts.

Workflow Folders

cloudcruise workflows folders                        # Top-level folders
cloudcruise workflows folders --path "Claims"        # Subfolders under a path
cloudcruise workflows folders --search invoice       # Search folders and workflows
cloudcruise workflows list --folder "Claims/EOB"     # Workflows in one folder (non-recursive)

Moving Workflows Between Environments

Export a workflow as a portable bundle and import it into another environment or workspace. Import always creates a new workflow:

cloudcruise workflows export <workflow_id> --profile staging > bundle.json
cloudcruise workflows import --file bundle.json --profile prod

# Or pipe directly
cloudcruise workflows export <workflow_id> --profile staging | cloudcruise workflows import --stdin --profile prod

The workspace is resolved from --workspace-id, then CLOUDCRUISE_WORKSPACE_ID, then the profile’s active workspace.

Deleting Workflows

Delete one or more workflows by id. The delete is permanent and asks no confirmation. Runs and results of the workflow are kept:

cloudcruise workflows delete <workflow_id> <workflow_id>

# Delete every workflow whose name starts with "[SCRATCH"
cloudcruise workflows list | jq -r '.[] | select(.name | startswith("[SCRATCH")) | .id' | xargs -r cloudcruise workflows delete

stdout is one array with an entry per id: { id, status: "deleted" | "not_found" | "error", message? }. The command continues past failures and exits non-zero if any id failed. A workflow’s webhooks are deleted with it. With OAuth, deleting requires the workspace Owner role.

Workflow Components

Components are reusable groups of nodes that can be pasted into many workflows. Updating a component automatically propagates the change to every workflow that embeds it (--no-propagate to skip). See the Workflow Components concept page for the full model.

cloudcruise components list                                                       # List components in your workspace
cloudcruise components get <component_id>                                         # Latest version + component_data
cloudcruise components get <component_id> --version-number 3                      # Specific historical version
cloudcruise components versions <component_id>                                    # Version history (newest first)
cloudcruise components usage <component_id>                                       # Workflows that embed this component
cloudcruise components create --name "Login flow" --file c.json                   # Create from JSON
cloudcruise components rename <component_id> --name "New name"                    # Rename only
cloudcruise components update <component_id> --file c.json --version-note "..."   # New version + propagate
cloudcruise components update <component_id> --file c.json --no-propagate         # Component-only update
cloudcruise components delete <component_id>                                      # Permanently delete (irreversible)

Before updating, check what propagation will affect:

cloudcruise components usage <component_id>                                       # List affected workflows
cloudcruise components update <component_id> --file c.json --version-note "..."   # Default: propagate to all

Error Codes

Error codes are the workspace-level IDs that a node’s error_on_false_message (Bool Condition), error_message (User Interaction), and selector_error_message (selector nodes) point to.

cloudcruise error-codes list                          # All codes in the workspace
cloudcruise error-codes list --workflow-id <id>       # Codes mapped to one workflow
cloudcruise error-codes get <error_code_id>

cloudcruise error-codes create --code CLAIM_NOT_FOUND --description "Claim not found in the portal"
cloudcruise error-codes update <error_code_id> --action input_required

error-codes create is find-or-create: if a code with the same name already exists (ignoring case and surrounding whitespace), it’s returned with "created": false and nothing changes, so it’s safe to run again. Use error-codes update to change an existing code. To use a code, put its returned id into the node field and save with workflows update. Saving links the code to the workflow. --action accepts alert (default), cancel, pause, retry, or input_required. Fields can also be passed as one JSON object via --file or --stdin, using the API field names (error_code, description, enriched_description, error_action).

Vault Credentials

cloudcruise vault list
cloudcruise vault get --user-id <user_id> --domain "https://app.example.com"
cloudcruise vault get --user-id <user_id> --domain "https://app.example.com" --decrypt

printf '%s' 's3cret' | cloudcruise vault create \
  --user-id <user_id> \
  --domain "https://app.example.com" \
  --user-name "user@example.com" \
  --password-stdin

cloudcruise vault clear-state --user-id <user_id> --domain "https://app.example.com"

vault create and vault update encrypt --user-name, --password, and --tfa-secret client-side, so they need an encryption key (CLOUDCRUISE_ENCRYPTION_KEY or one saved on the profile). Prefer --password-stdin and --tfa-secret-stdin over the plain flags, which are visible in ps output. Entries also support TFA (--tfa-method AUTHENTICATOR|EMAIL|SMS) and per-entry proxies (--proxy random|static|country|custom). You can also pass a pre-encrypted JSON payload via --file or --stdin. vault clear-state clears the stored browser state (cookies, localStorage, sessionStorage) for an entry. vault encrypt and vault decrypt work locally with the workspace encryption key and make no API call.

Secret Providers (1Password)

If your workspace has a 1Password connection, you can bind a vault entry to a 1Password item instead of storing a username and password. CloudCruise resolves the credentials from 1Password at run time, and the secret values are never stored in CloudCruise.

# 1. List secret-provider connections in your workspace
cloudcruise secret-providers list

# 2. List items a connection can see (each has a ref like op://vaultId/itemId)
cloudcruise secret-providers items <provider_id>

# 3. Create a provider-backed vault entry (no --user-name/--password)
cloudcruise vault create \
  --user-id acme-prod \
  --domain "https://acme.com" \
  --secret-provider-id <provider_id> \
  --secret-ref "op://vaultId/itemId"

# Update an existing entry the same way (optionally override the cache TTL)
cloudcruise vault update \
  --user-id acme-prod \
  --domain "https://acme.com" \
  --secret-provider-id <provider_id> \
  --secret-ref "op://vaultId/itemId" \
  --secret-cache-ttl-seconds 300

--secret-provider-id and --secret-ref must be passed together. --secret-cache-ttl-seconds is optional; omit it to use the connection’s default. Because provider-backed entries carry no --user-name/--password, no encryption key is required to create or update them.

Commands

Command	Description
`login`	Browser OAuth + PKCE login
`logout`	Remove saved credentials for the active profile
`whoami`	Show the authenticated account
`auth login`	Browser OAuth + PKCE login
`auth status`	Check authentication status (`--profile`)
`auth logout`	Remove saved credentials (`--profile`, `--all`)
`auth switch <name>`	Set the active profile
`auth profiles`	List all profiles
`auth workspace show` / `use` / `clear`	Same as `workspaces show` / `use` / `clear`
`workspaces list`	List workspaces for the authenticated user
`workspaces show`	Show the active workspace for a profile
`workspaces use <id>`	Set the active workspace for a profile
`workspaces clear`	Clear the active workspace for a profile
`workflows list`	List workflows (`--full`, `--folder <path>`)
`workflows folders`	List workflow folders (`--path`, `--search`, `--full`)
`workflows get <id>`	Get workflow definition with nodes and edges (`--version <version\|range>`, `--branch <branch_id>`)
`workflows versions <id>`	List workflow version history (`--limit`)
`workflows validate-input <id>`	Validate a run payload against the workflow’s input schema (`--file`, `--stdin`)
`workflows export <id>`	Export a workflow as a portable bundle
`workflows import`	Import a bundle as a new workflow (`--file`, `--stdin`)
`workflows update <id>`	Update workflow, creating a new version (`--file`, `--stdin`, `--version-note`)
`workflows delete <id...>`	Permanently delete one or more workflows
`components list`	List workflow components (`--full`)
`components get <id>`	Get component (`--version-number`)
`components versions <id>`	List component versions (`--limit`)
`components usage <id>`	List workflows that embed this component
`components create`	Create a new component (`--name`, `--file`, `--stdin`)
`components rename <id>`	Rename a component, no new version (`--name`)
`components update <id>`	Update component, creating a new version and propagating (`--file`, `--stdin`, `--version-note`, `--no-propagate`, `--source-workflow-id`)
`components delete <id>`	Permanently delete a component
`error-codes list`	List workspace error codes (`--workflow-id`)
`error-codes get <id>`	Get one error code
`error-codes create`	Find-or-create an error code by name (`--code`, `--description`, `--enriched-description`, `--action`, or `--file`/`--stdin`)
`error-codes update <id>`	Update an error code (same flags as create)
`run start <id>`	Start a run, returns session_id immediately (`--input`, `--debug`, `--dry-run`, `--no-notifications`)
`run get <id>`	Get run status, errors, screenshots, output (poll until the status is final; see Run Statuses)
`run list`	List runs (`--workflow`, `--status`, `--limit`, `--since`; defaults to the last 24 hours)
`run interrupt <id>`	Stop a running session
`run respond <id>`	Submit data to a run waiting on a User Interaction node (`--data`, `--file`, `--stdin`)
`run live-view <id>`	Get a fresh live-view connection (viewer URL + one-time auth token) for an active session
`run errors <id>`	Error analytics for a workflow (`--since`, `--limit`)
`run snapshots <id> <node_id>`	Debug snapshot metadata for a node
`snapshot fetch <sid> <nid>`	Download snapshot HTML, screenshots, and metadata (`--output-dir`, `--html`, `--image`)
`snapshot suggest [sid] [nid]`	Suggest unique XPath selectors (`--filter`, `--file`)
`snapshot test <xpath> [sid] [nid]`	Test an XPath against a snapshot (`--file`, `--count`)
`builder start`	Start a builder session (`--start-url`, `--name`, `--vault-user-id`, `--vault-domain`, `--proxy`, `--input-schema`, `--input`)
`builder edit`	Edit an existing workflow in the builder (`--workflow`, `--target-node`, `--use-example-inputs`, `--use-last-browser-state`)
`builder send <message>`	Send a message to the builder agent (returns immediately)
`builder await-turn`	Block until the current turn settles (`--poll-seconds`, `--timeout-seconds`)
`builder status`	Show conversation status (exit code encodes the state)
`builder respond`	Answer an input request from the agent (`--message-id`, `--value-stdin`, `--responses-stdin`)
`builder open`	Open the conversation in your browser
`builder conversations list`	List live builder conversations
`builder conversations get [id]`	Get an archived transcript (`--limit`, `--snapshot`, `--include-system`, `--output`)
`builder screenshot`	Screenshot of the builder browser (`--output`)
`builder html`	HTML of the current page (`--output`)
`builder workflow`	Current workflow definition
`builder messages`	Conversation messages (`--limit`, `--offset`, `--no-tail`)
`builder save`	Save the workflow (`-m`/`--message` for the version note)
`builder interrupt`	Interrupt the agent’s current processing
`builder end`	End the conversation and clean up
`vault list`	List vault entries (`--full`)
`vault get`	Get a vault entry (`--user-id`, `--domain`, `--decrypt`)
`vault create`	Create a vault entry (`--user-name`/`--password`, or `--secret-provider-id`/`--secret-ref` for 1Password)
`vault update`	Update a vault entry, including provider-backed bindings (`--secret-cache-ttl-seconds` to override the cache TTL)
`vault clear-state`	Clear stored browser state for a vault entry
`vault encrypt` / `vault decrypt`	Encrypt or decrypt a value locally with the workspace key
`secret-providers list`	List secret-provider connections in your workspace
`secret-providers items <provider-id>`	List items a secret-provider connection can see
`utils uuid`	Generate random UUIDs for new node IDs (`--count`)
`install --skills`	Install skill files for coding agents (`--target`)

Next Steps

Explore the Run API for detailed execution options
Learn about Vault API for secure credential management
Check out Workflow API to manage your workflows
Set up Webhooks for event notifications

Getting Started

Concepts

API Reference

SDK

Integrations

Overview

CLI Overview

Installation

Setup

Profiles

CI and Non-Interactive Use

Environment Variables

Coding Agent Integration

Staying Up to Date

Quick Start

Run Options

Error-Fix-Verify Loop

Debugging with Snapshots

Watching a Live Session

Responding to User Interaction

Builder Agent

Branches and Pull Requests

Merging with Conflicts

Workflow Folders

Moving Workflows Between Environments

Deleting Workflows

Workflow Components

Error Codes

Vault Credentials

Secret Providers (1Password)

Commands

Next Steps

​CLI Overview

​Installation

​Setup

​Profiles

​CI and Non-Interactive Use

​Environment Variables

​Coding Agent Integration

​Staying Up to Date

​Quick Start

​Run Options

​Error-Fix-Verify Loop

​Debugging with Snapshots

​Watching a Live Session

​Responding to User Interaction

​Builder Agent

​Branches and Pull Requests

​Merging with Conflicts

​Workflow Folders

​Moving Workflows Between Environments

​Deleting Workflows

​Workflow Components

​Error Codes

​Vault Credentials

​Secret Providers (1Password)

​Commands

​Next Steps

CLI Overview

Installation

Setup

Profiles

CI and Non-Interactive Use

Environment Variables

Coding Agent Integration

Staying Up to Date

Quick Start

Run Options

Error-Fix-Verify Loop

Debugging with Snapshots

Watching a Live Session

Responding to User Interaction

Builder Agent

Branches and Pull Requests

Merging with Conflicts

Workflow Folders

Moving Workflows Between Environments

Deleting Workflows

Workflow Components

Error Codes

Vault Credentials

Secret Providers (1Password)

Commands

Next Steps