Skip to content
Hexel StudioDocs

Hexel CLI

Install the hexel command-line interface, sign in with your Hexel account or an API key, and run your first commands.

On this page

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

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.

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 variableWhat it does
HEXEL_VERSIONInstall this version (for example v0.1.1) instead of the latest
HEXEL_INSTALL_DIRInstall 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>/:

FileContents
hexel_<version>_<os>_<arch>.tar.gzhexel for linux or darwin (macOS), amd64 or arm64
hexel_<version>_windows_<arch>.ziphexel.exe for Windows
SHA256SUMSSHA-256 checksum of every archive
SHA256SUMS.sigstore.jsonSigstore 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:

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.

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:

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 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, 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 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

  1. 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.

  2. See the tools your agents can use
    Bash
    hexel tools toolkit list
hexel tools tool list --toolkit GITHUB
hexel tools connection list
  3. 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.

Every command is listed in the command reference.