Skip to main content

​
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, and runs. It’s designed for coding agents to diagnose, fix, and verify workflow failures — but works just as well for manual use.

​
Installation

npm install -g @cloudcruise/cli
Or run without installing: 
npx @cloudcruise/cli --help

​
Setup

Log in with your browser — the CLI opens a browser window for OAuth: 
cloudcruise login
This opens a browser window for Google OAuth, then saves tokens to your OS keychain. After login, select the workspace you want to use: 
cloudcruise workspaces list
cloudcruise workspaces use <workspace_id>

​
API Key Login

If you have an existing API key, pass it via stdin: 
echo "sk_..." | cloudcruise auth login --api-key-stdin
Or set the CLOUDCRUISE_API_KEY environment variable.

​
Coding Agent Integration

Install skill files so your coding agent has the full CLI and workflow DSL reference: 
cloudcruise install --skills                  # Claude Code + Cursor
cloudcruise install --skills --target claude   # Claude Code only
cloudcruise install --skills --target cursor   # Cursor only
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.

​
Quick Start

cloudcruise workflows get <workflow_id> > workflow.json

cloudcruise run start <workflow_id> --wait

cloudcruise run get <session_id>

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

​
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
cloudcruise run get <session_id>
cloudcruise workflows get <workflow_id> > workflow.json

# 2. Reproduce — re-run with debug snapshots
cloudcruise run start <workflow_id> --input '{}' --wait --debug
# Note the new session_id from this debug run.

# 3. Inspect — examine both the screenshot and the HTML snapshot
cloudcruise run snapshots <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 '{}' --wait
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.

​
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

​
Commands

CommandDescription
loginBrowser OAuth + PKCE login
logoutRemove saved credentials
whoamiShow the authenticated account
auth loginBrowser OAuth + PKCE login
auth statusCheck authentication status (--profile)
auth logoutRemove saved credentials (--profile, --all)
auth switch <name>Set the active profile
auth profilesList all profiles
workspaces listList workspaces for the authenticated user
workspaces showShow the active workspace for a profile
workspaces use <id>Set the active workspace for a profile
workspaces clearClear the active workspace for a profile
workflows listList all workflows in your workspace
workflows get <id>Get workflow definition with nodes and edges
workflows versions <id>List workflow version history
workflows update <id> --file <path>Update workflow (creates a new version)
components listList workflow components (--full for all fields)
components get <id>Get component (--version-number for historical version)
components versions <id>List component versions (--limit)
components usage <id>List workflows that embed this component
components create --name <n> --file <path>Create a new component
components rename <id> --name <n>Rename a component (no new version)
components update <id> --file <path>Update component (creates new version + propagates)
components delete <id>Permanently delete a component
run start <id>Start a run (returns session_id)
run start <id> --waitStart and stream events until completion
run start <id> --wait --debugStart with debug snapshots on every node
run get <id>Get run status, errors, screenshots, output
run listList runs (supports --workflow, --status, --limit)
run interrupt <id>Stop a running session
run errors <id> --since 24hError analytics for a workflow
run snapshots <id> <node_id>Debug snapshots for a specific node
utils uuidGenerate a random UUID for new node IDs
install --skillsInstall skill files for coding agents

​
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