CloudCruise CLI

CLI for managing CloudCruise browser automation workflows and runs. Designed for coding agents to fix and edit CloudCruise workflows.

Install

npm install -g @cloudcruise/cli

Setup

Copy .env.example to .env, fill in the environment you want, then run cloudcruise login.

Coding Agent Integration

Claude Code — install the plugin from this repo's marketplace:

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

This registers all six skills (workflow build, test, debug, CLI and DSL reference) and keeps them updated with /plugin update cloudcruise.

Devin — an org admin adds this repo to the plugin manifest at Settings → Resources → Plugins → Configuration:

{
  "requiredPlugins": ["CloudCruise/cloudcruise-cli"]
}

Installs for the whole org from the next session; use optionalPlugins instead to make it opt-in. Devin reads the .claude-plugin/plugin.json manifest directly. Requires plugin access on your Devin org (currently closed beta — [email protected]).

Other agents (Cursor, or Claude Code without plugins) — install the skill files directly:

cloudcruise install --skills                  # Claude Code + Cursor
cloudcruise install --skills --target claude   # Claude Code only
cloudcruise install --skills --target cursor   # Cursor only

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

# List all workflows in your workspace
cloudcruise workflows list

# Get a workflow
cloudcruise workflows get <workflow_id> > workflow.json

# Start a run (returns { session_id } immediately; poll run get for completion)
cloudcruise run start <workflow_id>

# Start a debug run with snapshots on every node
cloudcruise run start <workflow_id> --debug

# Run the workflow but skip final submit/save actions (validates writes without submitting)
cloudcruise run start <workflow_id> --dry-run

# Start a run without workspace notifications (Slack/email) for this run
cloudcruise run start <workflow_id> --no-notifications

# Inspect a run (poll until the status is terminal)
cloudcruise run get <session_id>

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

Debugging with Snapshots

After a --debug run, use snapshot commands to diagnose failures:

# Download HTML snapshot, screenshots, and metadata for a node
cloudcruise snapshot fetch <session_id> <node_id>

# Suggest unique XPath selectors for interactive elements
cloudcruise snapshot suggest <session_id> <node_id>

# Test an XPath selector against a snapshot
cloudcruise snapshot test '//button[@id="submit"]' <session_id> <node_id>

# 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

All Commands

The CLI uses a loopback redirect on http://127.0.0.1 during login and stores reusable credentials in the OS keychain. run list defaults to the last 24 hours when --since is omitted. Use values like 24h, 7d, or 30m to adjust the time window.

License

MIT