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

# CLI Installation

> Install the Roboticks CLI via pip, pipx, or Homebrew. Python 3.10+. Verify with rbtk --version.

# Install the CLI

The CLI is the Python package `roboticks-cli` published to [PyPI](https://pypi.org/project/roboticks-cli/), sources at [github.com/roboticks-io/roboticks-cli](https://github.com/roboticks-io/roboticks-cli). It installs **two console scripts**: `rbtk` and `roboticks`. Use whichever you prefer — they're the same entry point.

## Requirements

<Check>**Python 3.10 or newer.** Check with `python3 --version`.</Check>
<Check>A POSIX shell or Windows PowerShell.</Check>

## Install

<Tabs>
  <Tab title="pipx (recommended)">
    `pipx` installs the CLI into a dedicated virtualenv so it cannot collide with project Python deps.

    ```bash theme={null}
    # If you don't have pipx
    python3 -m pip install --user pipx
    python3 -m pipx ensurepath

    # Install
    pipx install roboticks-cli
    ```

    Upgrade:

    ```bash theme={null}
    pipx upgrade roboticks-cli
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install --user roboticks-cli
    ```

    Use `pip install roboticks-cli` (no `--user`) inside a virtualenv. Avoid system-wide installs on managed Python — `pipx` is the better path.

    Upgrade:

    ```bash theme={null}
    pip install --user --upgrade roboticks-cli
    ```
  </Tab>

  <Tab title="Homebrew (macOS / Linux)">
    ```bash theme={null}
    brew install roboticks-io/tap/rbtk
    ```

    The Homebrew formula installs `rbtk` only; if you want the `roboticks` alias, symlink it:

    ```bash theme={null}
    ln -s "$(brew --prefix)/bin/rbtk" "$(brew --prefix)/bin/roboticks"
    ```

    Upgrade:

    ```bash theme={null}
    brew upgrade rbtk
    ```
  </Tab>

  <Tab title="From source">
    For SDK contributors:

    ```bash theme={null}
    git clone https://github.com/roboticks-io/roboticks-cli.git
    cd roboticks-cli
    pip install -e ".[dev]"
    pytest
    ```
  </Tab>
</Tabs>

## Verify

```bash theme={null}
rbtk --version
# rbtk 1.4.0 (commit a1b2c3, py3.12.4, darwin/arm64)

# Same binary under the other name
roboticks --help
```

## Shell completion

Tab completion is supported for Bash, Zsh, Fish, and PowerShell. Install once:

<Tabs>
  <Tab title="Bash">
    ```bash theme={null}
    rbtk completion bash | sudo tee /etc/bash_completion.d/rbtk > /dev/null
    ```
  </Tab>

  <Tab title="Zsh">
    ```bash theme={null}
    mkdir -p ~/.zsh/completions
    rbtk completion zsh > ~/.zsh/completions/_rbtk
    # Ensure ~/.zsh/completions is on your $fpath
    ```
  </Tab>

  <Tab title="Fish">
    ```bash theme={null}
    rbtk completion fish > ~/.config/fish/completions/rbtk.fish
    ```
  </Tab>

  <Tab title="PowerShell">
    ```powershell theme={null}
    rbtk completion powershell | Out-String | Invoke-Expression
    # Persist by appending the above to $PROFILE
    ```
  </Tab>
</Tabs>

Restart the shell. Completion covers commands, options, and dynamic values (project slugs, pool names, run IDs) when authenticated.

## Uninstall

```bash theme={null}
# pipx
pipx uninstall roboticks-cli

# pip
pip uninstall roboticks-cli

# Homebrew
brew uninstall rbtk
```

The CLI writes its keyring entry and `~/.config/roboticks/` directory; remove those manually if you want a clean slate:

```bash theme={null}
rm -rf ~/.config/roboticks
# macOS: also clear keychain
security delete-generic-password -s "io.roboticks.cli"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="`rbtk: command not found`">
    Your PATH is missing the install dir. Common locations:

    * `pipx`: `~/.local/bin` (Linux/macOS), `%USERPROFILE%\.local\bin` (Windows)
    * `pip --user`: `python3 -m site --user-base`/bin
    * Homebrew: `$(brew --prefix)/bin`

    Run `which python3` then `python3 -m pipx ensurepath` to fix `pipx` PATH automatically.
  </Accordion>

  <Accordion title="Python 3.10 not available">
    macOS:

    ```bash theme={null}
    brew install python@3.12
    ```

    Ubuntu 22.04 ships 3.10; on 20.04 use `deadsnakes`:

    ```bash theme={null}
    sudo add-apt-repository ppa:deadsnakes/ppa
    sudo apt install python3.12
    ```

    Then point pipx at the new interpreter:

    ```bash theme={null}
    pipx install --python python3.12 roboticks-cli
    ```
  </Accordion>

  <Accordion title="SSL errors on install">
    Behind a corporate proxy or MITM:

    ```bash theme={null}
    pip install --proxy http://proxy.corp:3128 roboticks-cli
    pip config set global.cert /path/to/corp-ca.pem
    ```
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Authenticate" icon="key" href="/cli/authentication">
    OAuth, API keys, GitHub OIDC.
  </Card>

  <Card title="Commands reference" icon="terminal" href="/cli/commands">
    All command groups, one page.
  </Card>
</CardGroup>