---
title: Hexel CLI
description: Install the hexel command-line interface, sign in with your Hexel
  account or an API key, and run your first commands.
url: https://hexelstudio.com/docs/cli/overview
---

`hexel` works with your Hexel Studio organization from a terminal or a CI job: organizations and workspaces, identity and access, the tools and skills your agents use, memory, Titan, which controls what your agents do, billing, and the audit log. It calls the same API as the console, at `https://api.hexelstudio.com/v1`.

## Install

<Tabs>
  <Tab title="macOS and Linux">
    ```bash
    curl -fsSL https://hexelstudio.com/install.sh | sh
    ```

    The script installs `hexel` to `/usr/local/bin` when you can write there, otherwise to `~/.local/bin`. If that directory isn't on your `PATH`, the script prints the line to add.
  </Tab>
  <Tab title="Windows">
    In PowerShell:

    ```powershell
    irm https://hexelstudio.com/install.ps1 | iex
    ```

    The script installs `hexel.exe` to `%LOCALAPPDATA%\hexel\bin` and adds that directory to your user `PATH`. Open a new terminal to use it.
  </Tab>
</Tabs>

Builds exist for Linux, macOS and Windows on x86-64 (`amd64`) and Arm (`arm64`). Each script downloads the latest release, checks it against the release's `SHA256SUMS` file and stops if the checksum doesn't match.

Check the installation:

```bash
hexel version
```

| Installer variable | What it does |
| --- | --- |
| `HEXEL_VERSION` | Install this version (for example `v0.1.1`) instead of the latest |
| `HEXEL_INSTALL_DIR` | Install to this directory |

```bash
curl -fsSL https://hexelstudio.com/install.sh | HEXEL_VERSION=v0.1.1 HEXEL_INSTALL_DIR="$HOME/bin" sh
```

### Download a release yourself

Every release is published under `https://cdn.hexelstudio.com/hexel-cli/<version>/`:

| File | Contents |
| --- | --- |
| `hexel_<version>_<os>_<arch>.tar.gz` | `hexel` for `linux` or `darwin` (macOS), `amd64` or `arm64` |
| `hexel_<version>_windows_<arch>.zip` | `hexel.exe` for Windows |
| `SHA256SUMS` | SHA-256 checksum of every archive |
| `SHA256SUMS.sigstore.json` | Sigstore signature of `SHA256SUMS` |

`https://cdn.hexelstudio.com/hexel-cli/latest` holds the newest version number.

```bash
v=$(curl -fsSL https://cdn.hexelstudio.com/hexel-cli/latest)
curl -fsSLO "https://cdn.hexelstudio.com/hexel-cli/$v/hexel_${v}_linux_amd64.tar.gz"
curl -fsSLO "https://cdn.hexelstudio.com/hexel-cli/$v/SHA256SUMS"
sha256sum --ignore-missing -c SHA256SUMS
tar -xzf "hexel_${v}_linux_amd64.tar.gz"
```

To check the signature too, download `SHA256SUMS.sigstore.json` and verify it with [cosign](https://docs.sigstore.dev/cosign/system_config/installation/):

```bash
cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/hexelstudio/hexel-cli/.github/workflows/release.yml@refs/tags/$v" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS
```

### Update and uninstall

When you run `hexel` in a terminal, it tells you when a newer release is out. It checks at most once a day, and never in CI or when `HEXEL_NO_UPDATE_CHECK` is set. To update, run the install command again.

To uninstall, sign out with `hexel auth logout`, delete the `hexel` binary, and delete the settings directory described in [Contexts and settings](https://hexelstudio.com/docs/cli/contexts#settings-file).

## Sign in

```bash
hexel auth login
```

`hexel` prints a link and a one-time code. Open the link, check that the code matches, and approve it with your Hexel account. Back in the terminal, `hexel` finishes signing in:

```text
Open https://identity.hexelstudio.com/activate?user_code=QDVL-WSSH
and confirm the code: QDVL-WSSH

Waiting for approval…
✓ Signed in as you@example.com.
```

`hexel` exchanges your sign-in for an [access token](https://hexelstudio.com/docs/identity/tokens) for the organization you work in, gets a new one when it expires, and gets a separate one when you switch organizations. When the sign-in itself expires, `hexel` asks you to run `hexel auth login` again.

Credentials are kept in your operating system's keychain: Keychain on macOS, Credential Manager on Windows, Secret Service on Linux. Where there is none, for example on a server or in WSL, they go to `credentials.json` in the [settings directory](https://hexelstudio.com/docs/cli/contexts#settings-file), readable only by you, and `hexel` says so.

```bash
hexel auth whoami     # who you are and the current context
hexel auth logout     # revoke the tokens and delete stored credentials
```

### In CI and scripts

Programs sign in as a [service user](https://hexelstudio.com/docs/identity/service-users) with an API key, not as a person. Set the key in the environment; `hexel` exchanges it for an access token on each run and never stores it:

```bash
export HEXEL_API_KEY="studio_live_..."
hexel tools toolkit list
```

You can create the service user and its key with `hexel` too. This needs the `directory:service_account:create` permission. A new service user can do nothing until you attach a policy, so attach only what the job needs:

```bash
hexel iam service-user create ci-deploy --description "Deploys from GitHub Actions"
hexel iam policy list                                   # find the policy the job needs
hexel iam service-user policy attach su_123 pol_ws_readonly
hexel iam api-key create su_123 --name github-actions --expires 90d
```

`hexel` prints the key once. Store it in your CI system's secrets, and revoke it with `hexel iam api-key revoke su_123 ak_456` when the job no longer needs it.

You can also store a key, for example on a build machine. `hexel` reads it from standard input, or prompts for it without echoing:

```bash
echo "$KEY" | hexel auth login --with-api-key
```

A service user always acts in its own organization. If you already have an access token, set `HEXEL_TOKEN` and `hexel` uses it as is. When several are present, `HEXEL_TOKEN` wins over `HEXEL_API_KEY`, which wins over stored credentials.

`hexel auth token` prints an access token for the current organization, for other tools:

```bash
curl -H "Authorization: Bearer $(hexel auth token)" https://api.hexelstudio.com/v1/workspaces
```

## First commands

<Steps>
  <Step title="Choose your organization and workspace">
    ```bash
    hexel org list
    hexel context set --org org_123
    hexel workspace list
    hexel context set --workspace ws_456
    ```

    The context remembers them, so later commands don't need the IDs. See [Contexts and settings](https://hexelstudio.com/docs/cli/contexts).
  </Step>
  <Step title="See the tools your agents can use">
    ```bash
    hexel tools toolkit list
    hexel tools tool list --toolkit GITHUB
    hexel tools connection list
    ```
  </Step>
  <Step title="Work with Titan">
    ```bash
    hexel titan deployment list
    hexel context set --deployment td-0123456789abcdef
    hexel titan approval list
    hexel titan approval approve apr_0123456789abcdef
    ```

    Approvals, sessions and the kill switch act on one Titan deployment: the context's, or the one you pass with `--deployment`.
  </Step>
</Steps>

Every command is listed in the [command reference](https://hexelstudio.com/docs/cli/commands).