> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt > Use this file to discover all available pages before exploring further. # Overview > Get started with the CloudCruise CLI # CLI Overview Open source at [https://github.com/CloudCruise/cloudcruise-cli](https://github.com/CloudCruise/cloudcruise-cli). Report bugs via [GitHub issues](https://github.com/CloudCruise/cloudcruise-cli/issues) or [Discord](https://discord.com/invite/MHjbUqedZF). 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 ```bash theme={null} npm install -g @cloudcruise/cli ``` Or run without installing: ```bash theme={null} npx @cloudcruise/cli --help ``` ## Setup Log in with your browser — the CLI opens a browser window for OAuth: ```bash theme={null} 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: ```bash theme={null} cloudcruise workspaces list cloudcruise workspaces use ``` ### API Key Login If you have an existing API key, pass it via stdin: ```bash theme={null} 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: ```bash theme={null} 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 ```bash theme={null} cloudcruise workflows get > workflow.json cloudcruise run start cloudcruise run get # poll until the run's status is terminal cloudcruise workflows update --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: ```bash theme={null} # 1. Diagnose — inspect the failed run cloudcruise run get cloudcruise workflows get > workflow.json # 2. Reproduce — re-run with debug snapshots cloudcruise run start --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 # 3. Inspect — examine both the screenshot and the HTML snapshot cloudcruise run snapshots # 4. Fix — edit the workflow, then push the update cloudcruise workflows update --file workflow.json --version-note "Fixed XPath" # 5. Verify — confirm the fix cloudcruise run start --input '{}' cloudcruise run get # 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. ## 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](/concepts/workflow-components) for the full model. ```bash theme={null} cloudcruise components list # List components in your workspace cloudcruise components get # Latest version + component_data cloudcruise components get --version-number 3 # Specific historical version cloudcruise components versions # Version history (newest first) cloudcruise components usage # Workflows that embed this component cloudcruise components create --name "Login flow" --file c.json # Create from JSON cloudcruise components rename --name "New name" # Rename only cloudcruise components update --file c.json --version-note "…" # New version + propagate cloudcruise components update --file c.json --no-propagate # Component-only update cloudcruise components delete # Permanently delete (irreversible) ``` **Before updating, check what propagation will affect:** ```bash theme={null} cloudcruise components usage # List affected workflows cloudcruise components update --file c.json --version-note "…" # Default: propagate to all ``` ## Secret Providers (1Password) If your workspace has a [1Password connection](/integrations/1password), 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. ```bash theme={null} # 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 # 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 \ --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 \ --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 ` | 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 ` | 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 ` | Get workflow definition with nodes and edges | | `workflows versions ` | List workflow version history | | `workflows update --file ` | Update workflow (creates a new version) | | `components list` | List workflow components (`--full` for all fields) | | `components get ` | Get component (`--version-number` for historical version) | | `components versions ` | List component versions (`--limit`) | | `components usage ` | List workflows that embed this component | | `components create --name --file ` | Create a new component | | `components rename --name ` | Rename a component (no new version) | | `components update --file ` | Update component (creates new version + propagates) | | `components delete ` | Permanently delete a component | | `run start ` | Start a run, returns session\_id immediately (non-blocking) | | `run start --debug` | Start with debug snapshots on every node | | `run get ` | Get run status, errors, screenshots, output (poll until terminal) | | `run list` | List runs (supports `--workflow`, `--status`, `--limit`) | | `run interrupt ` | Stop a running session | | `run errors --since 24h` | Error analytics for a workflow | | `run snapshots ` | 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 ` | 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](/run-api/start-a-run) for detailed execution options * Learn about [Vault API](/vault-api/create-vault-entry) for secure credential management * Check out [Workflow API](/workflow-api/get-workflows) to manage your workflows * Set up [Webhooks](/webhooks-api/replay-webhooks) for event notifications