> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Wherobots CLI

> Submit and manage Job runs, stream logs, and access the full Wherobots API from your terminal.

<Badge color="purple">Public Preview</Badge>

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.

<Note>
  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.
</Note>

## Quickstart

Already familiar with CLIs? Get up and running quickly.

<Accordion title="Quickstart" icon="stopwatch">
  1. Clone and install the CLI:
     ```bash theme={"system"}
     gh repo clone wherobots/wbc-cli && cd wbc-cli && ./scripts/install-release.sh
     ```
  2. Set your API key:
     ```bash theme={"system"}
     export WHEROBOTS_API_KEY='<your-api-key>'
     ```
  3. Verify the connection:
     ```bash theme={"system"}
     wherobots api --tree
     ```
</Accordion>

## Benefits

The Wherobots CLI provides a powerful and flexible interface to Wherobots Cloud, with features designed for both interactive use and automation:

<AccordionGroup>
  <Accordion title="Built for AI-assisted workflows" icon="microchip">
    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](/develop/agent-skills) to give your agent domain-specific Wherobots knowledge for more accurate results.
  </Accordion>

  <Accordion title="Always up to date" icon="rotate">
    Commands are generated dynamically from the Wherobots API. New endpoints and capabilities are available immediately without a CLI update.
  </Accordion>

  <Accordion title="Submit and monitor jobs from your terminal" icon="terminal">
    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.
  </Accordion>

  <Accordion title="Flexible output for scripting and automation" icon="gears">
    Switch between human-readable table output and JSON output to integrate the CLI into shell scripts, CI/CD pipelines, and orchestration tools.
  </Accordion>

  <Accordion title="Dry-run mode for safe exploration" icon="flask">
    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.
  </Accordion>
</AccordionGroup>

## Before you start

Before using the Wherobots CLI, ensure you have the following:

<AccordionGroup cols={2}>
  <Accordion title="Wherobots requirements" icon="cloud">
    * A **Wherobots Account** within a Community, Professional or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-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](/get-started/wherobots-cloud/api-keys).
  </Accordion>

  <Accordion title="Local requirements" icon="laptop">
    * [**GitHub CLI** (`gh`)](https://cli.github.com/) installed and authenticated with access to the `wherobots/wbc-cli` repository.
  </Accordion>
</AccordionGroup>

## Install the CLI

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

<Steps>
  <Step title="Clone the CLI repository">
    ```bash theme={"system"}
    gh repo clone wherobots/wbc-cli
    ```
  </Step>

  <Step title="Navigate to the repository">
    ```bash theme={"system"}
    cd wbc-cli
    ```
  </Step>

  <Step title="Run the install script">
    ```bash theme={"system"}
    ./scripts/install-release.sh
    ```

    If prompted for a password in the terminal, enter your local system password.
  </Step>
</Steps>

## Configure authentication

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

<Steps>
  <Step title="Export your API key">
    Set the `WHEROBOTS_API_KEY` environment variable in your shell:

    ```bash theme={"system"}
    export WHEROBOTS_API_KEY='<your-api-key>'
    ```

    To persist this across sessions, add the export to your shell profile (for example, `~/.zshrc` or `~/.bashrc`).

    <Warning>
      Do not commit your API key to version control. Use a secrets manager or environment-specific configuration to keep it safe.
    </Warning>
  </Step>

  <Step title="Verify the connection">
    Run `wherobots api --tree` to confirm the CLI can reach Wherobots Cloud. You should see a tree of available commands, or an error if the connection failed.

    <Tip>
      If you encounter issues, ensure your API key is correctly set and that you have network connectivity to Wherobots Cloud.
    </Tip>
  </Step>
</Steps>

### Environment variables

The CLI uses the following environment variables for configuration:

| Variable                | Description                 | Default                           |
| ----------------------- | --------------------------- | --------------------------------- |
| `WHEROBOTS_API_KEY`     | **Required.** API key       | —                                 |
| `WHEROBOTS_API_URL`     | API base URL                | `https://api.cloud.wherobots.com` |
| `WHEROBOTS_UPLOAD_PATH` | S3 root for file uploads    | Auto-resolved                     |
| `OPENAPI_CACHE_TTL`     | OpenAPI spec cache duration | `15m`                             |
| `OPENAPI_HTTP_TIMEOUT`  | Spec fetch timeout          | `30s`                             |

## 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](/develop/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:

<AccordionGroup>
  <Accordion title="Error: WHEROBOTS_API_KEY is not set" icon="circle-question">
    **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).
  </Accordion>

  <Accordion title="401 Unauthorized" icon="circle-question">
    **Cause:** The API key is invalid or expired.

    **Solution:**

    * Generate a new API key in the Wherobots Cloud console. See [API Keys](/get-started/wherobots-cloud/api-keys).
    * Confirm you copied the full key without leading or trailing whitespace.
  </Accordion>

  <Accordion title="Command not found: wherobots" icon="circle-question">
    **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.
  </Accordion>

  <Accordion title="OpenAPI spec fetch failed" icon="circle-question">
    **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`.
  </Accordion>
</AccordionGroup>

## Next steps

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

<CardGroup cols={2}>
  <Card title="Agentic terminal usage" icon="message-bot" href="/develop/cli-agentic-usage">
    Use the CLI with AI-powered terminals like Claude Code and OpenCode for natural language job management.
  </Card>

  <Card title="MCP Server" icon="microchip" href="/develop/mcp/mcp-server-setup">
    Configure and use the MCP Server for advanced data exploration and query generation.
  </Card>
</CardGroup>