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

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>

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>

cloudcruise run get <session_id>   # poll until the run's status is terminal

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 '{}' --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 — 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 '{}'
cloudcruise run get <new_session_id>   # poll until the run's status is terminal

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.

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/link. Only works while the session is still active.

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

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 — 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
`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
`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 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 list`	List 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 immediately (non-blocking)
`run start <id> --debug`	Start with debug snapshots on every node
`run get <id>`	Get run status, errors, screenshots, output (poll until terminal)
`run list`	List runs (supports `--workflow`, `--status`, `--limit`)
`run interrupt <id>`	Stop a running session
`run live-view <id>`	Get a fresh live-view connection (viewer URL + one-time auth token) for an active session
`run errors <id> --since 24h`	Error analytics for a workflow
`run snapshots <id> <node_id>`	Debug snapshots for a specific node
`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)
`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 a random UUID for new node IDs
`install --skills`	Install 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

Getting Started

Concepts

API Reference

SDK

Integrations

Overview

CLI Overview

Installation

Setup

Coding Agent Integration

Quick Start

Error-Fix-Verify Loop

Watching a Live Session

Workflow Components

Secret Providers (1Password)

Commands

Next Steps

​CLI Overview

​Installation

​Setup

​API Key Login

​Coding Agent Integration

​Quick Start

​Error-Fix-Verify Loop

​Watching a Live Session

​Workflow Components

​Secret Providers (1Password)

​Commands

​Next Steps

CLI Overview

Installation

Setup

API Key Login

Coding Agent Integration

Quick Start

Error-Fix-Verify Loop

Watching a Live Session

Workflow Components

Secret Providers (1Password)

Commands

Next Steps