Skip to main content
Public Preview The Wherobots CLI wraps the entire Wherobots Cloud API into a single binary. Submit jobs, stream logs, filter runs, and hit any API endpoint — all from your terminal. Commands are generated directly from the API spec, so every endpoint is a CLI command and new capabilities show up without a CLI update. Use it from any terminal: VS Code, Cursor, Claude Code, OpenCode, or a plain shell.
The CLI is designed for interactive and agent-driven use. Commands and their underlying APIs may change between releases. Do not take a dependency on this CLI for recurring production pipelines.

​
Quickstart

Already familiar with CLIs? Get up and running quickly.
  1. Clone and install the CLI: 
    gh repo clone wherobots/wbc-cli && cd wbc-cli && ./scripts/install-release.sh
  2. Set your API key: 
    export WHEROBOTS_API_KEY='<your-api-key>'
  3. Verify the connection: 
    wherobots api --tree

​
Benefits

The Wherobots CLI provides a powerful and flexible interface to Wherobots Cloud, with features designed for both interactive use and automation:
Use the CLI from AI-powered terminals like Claude Code, OpenCode, and Cursor. Your AI assistant translates natural language into the correct CLI commands. Install agent skills to give your agent domain-specific Wherobots knowledge for more accurate results.
Commands are generated dynamically from the Wherobots API. New endpoints and capabilities are available immediately without a CLI update.
Create Job runs, stream logs in real time, and check metrics without leaving the command line. Local script files are automatically uploaded to managed storage.
Switch between human-readable table output and JSON output to integrate the CLI into shell scripts, CI/CD pipelines, and orchestration tools.
Use the --dry-run flag to print the equivalent curl command instead of executing it, so you can inspect exactly what the CLI will send.

​
Before you start

Before using the Wherobots CLI, ensure you have the following:
  • A Wherobots Account within a Community, Professional or Enterprise Organization. See Create a Wherobots Account. While the Wherobots CLI can be used with any Organization Edition, some API features, like job runs, require a paid subscription.
  • A Wherobots API key. See API Keys.
  • GitHub CLI (gh) installed and authenticated with access to the wherobots/wbc-cli repository.

​
Install the CLI

Clone the repository and run the install script to download the latest release binary:
1

Clone the CLI repository

gh repo clone wherobots/wbc-cli
2

Navigate to the repository

cd wbc-cli
3

Run the install script

./scripts/install-release.sh
If prompted for a password in the terminal, enter your local system password.

​
Configure authentication

The CLI authenticates with your Wherobots API key, passed through an environment variable.
1

Export your API key

Set the WHEROBOTS_API_KEY environment variable in your shell:
export WHEROBOTS_API_KEY='<your-api-key>'
To persist this across sessions, add the export to your shell profile (for example, ~/.zshrc or ~/.bashrc).
Do not commit your API key to version control. Use a secrets manager or environment-specific configuration to keep it safe.
2

Verify the connection

Run wherobots --tree to confirm the CLI can reach Wherobots Cloud. You should see a tree of available commands, or an error if the connection failed.
If you encounter issues, ensure your API key is correctly set and that you have network connectivity to Wherobots Cloud.

​
Environment variables

The CLI uses the following environment variables for configuration:
VariableDescriptionDefault
WHEROBOTS_API_KEYRequired. API key—
WHEROBOTS_API_URLAPI base URLhttps://api.cloud.wherobots.com
WHEROBOTS_UPLOAD_PATHS3 root for file uploadsAuto-resolved
OPENAPI_CACHE_TTLOpenAPI spec cache duration15m
OPENAPI_HTTP_TIMEOUTSpec fetch timeout30s

​
Add agent skills

If you use the CLI from an agentic terminal (OpenCode, Claude Code, Cursor, or similar), installing Wherobots agent skills gives the agent structured context about Wherobots workflows, APIs, and best practices. This leads to fewer errors and more reliable multi-step operations.
If you use the Wherobots VS Code Extension, skills are bundled with the extension and available automatically in Copilot Chat and Claude Code — no manual installation needed.
Install all Wherobots skills: 
npx skills add -g wherobots/agent-skills
Or install a specific skill: 
npx skills add wherobots/agent-skills --skill wherobots-usage
For more information on skills, see the Skills CLI documentation. To see available Wherobots skills, visit the wherobots/agent-skills repository. For agentic terminal usage patterns, see Agentic terminal usage.

​
Troubleshooting

The following are common issues you may encounter when using the Wherobots CLI, along with their causes and solutions:
Cause: The CLI cannot find an API key in your environment.Solution:
  • Export the variable: export WHEROBOTS_API_KEY='<your-key>'.
  • Check that the variable is set in the shell session where you are running the CLI (not just in another terminal).
Cause: The API key is invalid or expired.Solution:
  • Generate a new API key in the Wherobots Cloud console. See API Keys.
  • Confirm you copied the full key without leading or trailing whitespace.
Cause: The binary is not on your PATH.Solution:
  • Verify the install directory: ls ~/.local/bin/wherobots.
  • Add the directory to your PATH: export PATH="$HOME/.local/bin:$PATH".
  • If you built from source, the binary is at bin/wherobots inside the repository.
Cause: The CLI cannot reach the Wherobots API to download the specification.Solution:
  • Check your network connection and proxy settings.
  • The CLI falls back to a cached spec at ~/.cache/wherobots/spec.json. If the cache is stale, delete it and retry.
  • Increase the timeout with OPENAPI_HTTP_TIMEOUT=60s.

​
Next steps

Review the following resources to explore more features of Wherobots Cloud and the CLI:

Agentic terminal usage

Use the CLI with AI-powered terminals like Claude Code and OpenCode for natural language job management.

MCP Server

Configure and use the MCP Server for advanced data exploration and query generation.