Skip to main content
Public Preview The Wherobots Command Line Interface (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. Install the CLI:
  2. Sign in:
    1. Confirm that the confirmation code matches the one printed in the terminal, select your Organization, and authorize the CLI.
  3. Verify the connection to confirm the CLI can reach Wherobots Cloud:

​
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 Professional, Innovation, 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 way to authenticate: sign in from your browser with wherobots auth login, or a Wherobots API key for CI and scripts. See API Keys.
  • A Unix-like shell (bash, zsh, or similar) with curl available.

​
Install the CLI

Run the install script to download the latest release binary:
1

Run the install script

If prompted for a password in the terminal, enter your local system password.

​
Configure authentication

The CLI supports two ways to authenticate with Wherobots Cloud:
  • Browser sign-in (OAuth) — sign in interactively with wherobots auth login. Best for local, interactive, and agent-driven use.
  • API key — set the WHEROBOTS_API_KEY environment variable. Best for CI, scripts, and other non-interactive environments.
When both are present, WHEROBOTS_API_KEY takes precedence, so scripts behave predictably.

​
Sign in with your browser (OAuth)

1

Start the sign-in flow

The command prints a one-time confirmation code and opens your browser. Sign in to Wherobots, confirm the code matches, and select your Organization to authorize the CLI.
No browser on this machine (for example, over SSH)? Run wherobots auth login --no-browser to print just the sign-in URL, then open it on any other device to complete the confirmation.
Run wherobots auth status to see which credential is active, and wherobots auth logout to sign out.
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.

​
Use an API key

You can also login to Wherobots Cloud using an API key.
1

Export your API key

Set the WHEROBOTS_API_KEY environment variable in your shell:
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:

​
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. See Agent Skills for installation instructions and the full list of available skills.

​
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 a browser sign-in or an API key in your environment.Solution:
  • Sign in from your browser: wherobots auth login. Run wherobots auth status to confirm the session is active.
  • Or export an API key: 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: Your credentials are invalid or expired.Solution:
  • If you signed in from your browser, your session may have expired. Run wherobots auth login again, or check wherobots auth status.
  • If you use an API key, generate a new one 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.