docs · start
Install#
Install Hekma with the one-line installer, Homebrew, Cargo or a release archive, then check it with hekma --version. Hekma is a single binary (plus a short alias, hkm) with nothing else to install, and it runs on macOS, Linux and Windows. This page also covers updating, uninstalling and where Hekma keeps its data.
Choose a method#
| Method | Platforms | Updates with |
|---|---|---|
| Installer | macOS, Linux, Windows | hekma self-update |
| Homebrew | macOS, Linux | brew upgrade or hekma self-update |
| Cargo, from crates.io | Any platform Rust supports | cargo install or hekma self-update |
| Release archive | macOS, Linux x86_64, Windows x86_64 | hekma self-update |
| From source | Any platform Rust supports | Rebuild |
Prebuilt binaries exist for macOS (Intel and Apple Silicon), Linux x86_64 (glibc) and Windows x86_64. On anything else, such as Linux on ARM, use Cargo.
Install with the installer#
On macOS or Linux:
curl -fsSL https://cli.ktesio.dev/hekma/install.sh | shOn Windows, in PowerShell:
irm https://cli.ktesio.dev/hekma/install.ps1 | iexThe installer picks the best way to install for your machine:
- If Hekma (or the older
kt) is already installed, it updates it the same way it was installed: Homebrew withbrew upgrade, Cargo withcargo install, otherwise by replacing the binaries where they are. - On a new macOS or Linux machine, it uses Homebrew if you have it, then Cargo if you have it, then downloads a prebuilt binary.
- On a new Windows machine, it uses Cargo if you have it, then downloads a prebuilt binary.
A downloaded binary is checked against its published SHA-256 checksum before it is installed. It goes to ~/.local/bin on macOS and Linux, or %LOCALAPPDATA%\hekma\bin on Windows. If that folder is not on your PATH, the installer says so:
warning: /Users/you/.local/bin is not on PATH. Add it before running hekma.Add the folder to your PATH in your shell profile and open a new terminal. The installer never edits your shell profile, never installs Homebrew or Rust for you, and refuses to overwrite a hekma or hkm command that is not Hekma.
Installer settings#
Set these on the sh side of the pipe, so the script sees them:
curl -fsSL https://cli.ktesio.dev/hekma/install.sh | HEKMA_INSTALL_METHOD=binary HEKMA_INSTALL_DIR="$HOME/bin" shOn Windows, set them in the session first, for example $env:HEKMA_INSTALL_METHOD = "binary", then run the installer.
| Variable | Values | Effect |
|---|---|---|
HEKMA_INSTALL_METHOD | auto (default), brew, cargo, binary | Forces one install method. Windows accepts auto, cargo and binary. |
HEKMA_INSTALL_DIR | a folder | Where a downloaded binary goes. Ignored for Homebrew and Cargo installs. |
HEKMA_INSTALL_DRY_RUN | 1 | Prints what the installer would do, and changes nothing. |
Each variable also works with its older KTESIO_ name (KTESIO_INSTALL_METHOD, KTESIO_INSTALL_DIR, KTESIO_INSTALL_DRY_RUN). If both are set, the HEKMA_ name wins.
A dry run on a Mac with no Homebrew or Cargo:
curl -fsSL https://cli.ktesio.dev/hekma/install.sh | HEKMA_INSTALL_DRY_RUN=1 shDRY RUN: install prebuilt aarch64-apple-darwin (hekma + hkm) to /Users/you/.local/binInstall with Homebrew#
brew install ktesio/tap/hekmaThe formula installs the prebuilt release binaries, hekma and hkm, on macOS and Linux x86_64.
Install from crates.io#
cargo install hekmaThis builds Hekma from source and puts hekma and hkm in ~/.cargo/bin. It needs Rust 1.96.1 or later; get Rust from rustup.rs.
Install from a release#
Download the archive for your platform from GitHub Releases:
| Platform | Archive |
|---|---|
| macOS, Apple Silicon | hekma-v0.11.0-aarch64-apple-darwin.tar.gz |
| macOS, Intel | hekma-v0.11.0-x86_64-apple-darwin.tar.gz |
| Linux x86_64 (glibc) | hekma-v0.11.0-x86_64-unknown-linux-gnu.tar.gz |
| Windows x86_64 | hekma-v0.11.0-x86_64-pc-windows-msvc.zip |
Each archive has a matching .sha256 file, and every release also has a checksums.txt covering all of them. Check the archive, unpack it, and put both hekma and hkm in a folder on your PATH:
shasum -a 256 -c hekma-v0.11.0-aarch64-apple-darwin.tar.gz.sha256
tar -xzf hekma-v0.11.0-aarch64-apple-darwin.tar.gz
mv hekma hkm ~/.local/bin/On Linux, use sha256sum -c instead of shasum -a 256 -c.
Install from source#
git clone https://github.com/Ktesio/hekma.git
cd hekma
git checkout v0.11.0
cargo install --path crates/hekmaThe repository is a workspace of several crates, so point --path at crates/hekma; cargo install --path . fails. You need Rust 1.96.1 or later (the repository's toolchain file selects it for you if you use rustup), plus the usual native build tools: Xcode Command Line Tools on macOS, a C compiler on Linux, or the MSVC build tools on Windows.
Check the install#
hekma --version
hkm --versionhekma 0.11.0
hekma 0.11.0hkm is a short alias for hekma: the same program under a shorter name, so both print hekma. Use whichever you prefer. Next, try the Quickstart.
Updating Hekma#
Update with:
hekma self-updateself-update works out how Hekma was installed and updates it the same way:
| Installed with | What self-update runs |
|---|---|
| Homebrew | brew upgrade ktesio/tap/hekma |
Cargo (the binary is in ~/.cargo/bin or $CARGO_HOME/bin) | cargo install hekma --force |
| Anything else (installer download, release archive) | Downloads the latest release archive, checks its SHA-256 checksum, and replaces hekma and hkm where they are |
It reports any failure. For a downloaded install that is already current, it says Hekma is already up to date and changes nothing. Agents are separate programs, so updating Hekma does not stop or restart them; the next hekma command, now the new version, adopts any detached agent as usual.
The update notice#
Before most commands, Hekma checks GitHub for a newer release, at most once an hour, waiting no more than three seconds. If there is one, it prints a notice on stderr:
! Update available: Hekma 0.12.0 is available (current 0.11.0). Update: hekma self-update(The version numbers above are an example.) A failed check is silent and never changes a command's result. The last result is cached in ktesio/update-check.json inside your user cache folder.
Turn off update checks#
Set any of these to a value other than empty, 0, false, no or off:
| Variable | Notes |
|---|---|
HEKMA_NO_UPDATE_CHECK | The preferred name. |
KTESIO_NO_UPDATE_CHECK | The older name; still honoured. |
CI | Set by most CI services, so checks are already off there. |
export HEKMA_NO_UPDATE_CHECK=1This only stops the automatic check. hekma self-update still works when you run it.
Uninstall#
Remove the binaries the same way you installed them:
| Installed with | Remove with |
|---|---|
| Homebrew | brew uninstall ktesio/tap/hekma |
| Cargo | cargo uninstall hekma |
| Installer download or release archive | Delete hekma and hkm from their folder (~/.local/bin or %LOCALAPPDATA%\hekma\bin by default) |
Stop your agents first (hekma agent stop NAME), because uninstalling does not stop running agent processes. Uninstalling also leaves Hekma's data in place, so a reinstall picks up your agents again. To remove everything, delete the state directory as well.
Where Hekma keeps its data#
Everything Hekma stores lives in one state directory: the database of agents, usage and budgets (state.db), each agent's Agent Home with its config and logs, and the optional secrets.toml.
| OS | Default location |
|---|---|
| macOS | ~/Library/Application Support/ktesio |
| Linux | $XDG_DATA_HOME/ktesio, or ~/.local/share/ktesio when XDG_DATA_HOME is not set |
| Windows | %APPDATA%\ktesio\data |
The folder is called ktesio, the product's old name, so installations from before the rename keep their data where it was.
To use another folder, set HEKMA_STATE_DIR (or the older KTESIO_STATE_DIR) to an absolute path. A relative path is refused, and if you set both names to different folders, Hekma refuses to guess and stops with an error. Separate state directories are fully separate fleets, which is handy for tests and scripts:
export HEKMA_STATE_DIR="$HOME/hekma-test-state"Read next#
- Quickstart: run your first supervised agent.
- Upgrade from kt: move from the older
ktcommand. - Troubleshooting: installer and update problems.
- Exit codes and environment: every environment variable Hekma reads.