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.For pipelines, use the Runs REST API or the Wherobots Apache Airflow Provider.

​
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. JSON output is easier for your AI assistant or a one-off shell script to parse.
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. See Create a Wherobots Account.
  • A way to authenticate: sign in from your browser with wherobots auth login, or a Wherobots API key for 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 scripts and other non-interactive use.
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:

​
Use the CLI from an agentic terminal

Agentic coding tools such as OpenCode, Claude Code, Cursor, and other AI-powered terminals run commands in your terminal, so they can use the Wherobots CLI as installed. The agentic terminal translates a plain-language request into wherobots commands and flags, can chain steps such as submitting a job, waiting for it to finish, and fetching its logs, and summarizes the output. When a command fails, the agentic terminal can use the error message to suggest a fix and retry. To get started, install the CLI and sign in (see Install the CLI and Configure authentication), then open your agentic terminal.
Wherobots recommends using the latest high-performing AI model available in your agentic terminal for the best results, such as Claude Opus, GPT Codex, or Gemini Pro.

​
Add agent skills

Agent skills give your agentic terminal domain-specific knowledge about Wherobots so it produces more accurate commands and better interprets results. Without skills, the agent relies only on CLI help text and its general training data. With skills installed, it has structured context about Wherobots workflows, APIs, and best practices, which leads to fewer errors and more reliable multi-step operations. See Agent Skills for installation instructions and the full list of available skills.

​
Example prompts

​
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:

Agent Skills

Install Wherobots agent skills so your agentic terminal produces more accurate CLI commands.

MCP Server

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