docs · guides

Upgrade from kt#

Hekma is the new name of the product first released as Ktesio, with the kt command (versions 0.1.1 to 0.7.0). To upgrade, re-run the installer or your package manager; you get the hekma command and its short alias hkm. Your data does not move: Hekma reads the same state directory kt used, so every agent, budget, usage record and secret is still there.

TL;DR#

Re-run the installer. It finds your kt install and upgrades it the way it was installed (Homebrew, Cargo or a downloaded binary):

curl -fsSL https://cli.ktesio.dev/hekma/install.sh | sh
irm https://cli.ktesio.dev/hekma/install.ps1 | iex

Then check it and look at your fleet:

hekma --version
hekma agent list

The old kt binary keeps working at its old version but can no longer update itself; remove it when you are ready. The steps for each install channel are below.

Your data stays where it is#

Hekma uses the same default state directory as kt (it is still named ktesio) and the same database. Upgrading does not move, merge, reset or delete anything (Hekma only adds what it needs to the database the first time it opens it): registered agents, usage history, budgets and rates, memory backings, secrets and their file permissions all carry over. You do not need to register agents again.

If you set KTESIO_STATE_DIR to use another folder, it still works. See the environment map.

What changed#

Before (up to 0.7.0)Now
Command kthekma, plus the short alias hkm (the same program)
Crate ktesio on crates.iohekma (the ktesio crate stays published, frozen at 0.7.0)
Library ktesio-enginehekma-engine
Release archives ktesio-v…hekma-v…
Homebrew formula ktesio/tap/ktesioktesio/tap/hekma (same tap)
KTESIO_* environment variablesStill honoured, with preferred HEKMA_* names
Docs at docs.ktesio.devhekma.ktesio.dev/docs

These did not change: the JSON output formats and their schema versions, the exit codes, the KTESIO_USAGE line agents print to report usage, the adapter contract (contract_version = "1.0.0"), and the state directory.

Since 0.9.0, Hekma is open source under the Apache-2.0 license. Earlier releases keep the license they shipped with.

Migrating each install channel#

Homebrew#

The formula was renamed inside the same tap, and the tap tells Homebrew about the rename, so a normal upgrade moves you over:

brew upgrade ktesio/tap/hekma

Newer Homebrew versions may first refuse with a message about an untrusted tap. Trust the tap once with brew trust ktesio/tap and run the upgrade again. If the upgrade does not pick up the rename, install the new formula directly with brew install ktesio/tap/hekma.

Cargo#

cargo install hekma --force
cargo uninstall ktesio

The first command installs hekma and hkm into ~/.cargo/bin. The second removes the old kt, which Cargo would otherwise leave behind.

Downloaded binary#

If you installed kt with the installer or from a release archive, re-running the installer puts hekma and hkm in the same folder as kt and leaves kt alone, with a note:

warning: the retired kt binary was left at /Users/you/.local/bin/kt — Hekma 0.8.0 replaced it with hekma + hkm; remove it with: rm /Users/you/.local/bin/kt

To upgrade by hand instead, download the hekma-v… archive for your platform from GitHub Releases and put both hekma and hkm on your PATH, taken from the same release. Install lists the archives.

Remove the old binary when you no longer need it:

rm "$(command -v kt)"

Windows#

On Windows, a new install goes to %LOCALAPPDATA%\hekma\bin, but an upgrade puts hekma next to your existing kt.exe (for example in %LOCALAPPDATA%\ktesio\bin), so the old folder on your PATH keeps working. Stop any running kt or hekma processes before you upgrade.

Why kt self-update stops working#

From 0.8.0 on, releases publish only hekma-v… archives. An old kt self-update looks for ktesio-v… archives, which no longer exist, so it fails with a download error and changes nothing. Use the installer, Homebrew or Cargo as described above; that works from every kt release, 0.1.1 through 0.7.0. After that, hekma self-update keeps you current.

Environment settings map#

Every KTESIO_* setting still works. Prefer the HEKMA_* names in new scripts.

Old nameNew nameNotes
KTESIO_STATE_DIRHEKMA_STATE_DIRIf both are set, they must name the same folder; different folders is an error.
KTESIO_NO_UPDATE_CHECKHEKMA_NO_UPDATE_CHECKEither one turns the update check off. CI also turns it off.
KTESIO_INSTALL_METHOD, KTESIO_INSTALL_DIR, KTESIO_INSTALL_DRY_RUNHEKMA_INSTALL_METHOD, HEKMA_INSTALL_DIR, HEKMA_INSTALL_DRY_RUNInstaller settings. The HEKMA_ name wins if both are set.
KTESIO_USAGEunchangedThe line agents print to report usage. Keep printing it.
KTESIO_MEMORY_DIRunchangedThe variable the built-in mock kind receives for a memory backing.

Installer settings must be set on the sh side of the pipe. HEKMA_INSTALL_METHOD=binary curl … | sh sets the variable for curl, not for the installer:

curl -fsSL https://cli.ktesio.dev/hekma/install.sh | HEKMA_INSTALL_METHOD=binary sh

FAQ#

Is hkm a different program? No. hekma and hkm are the same program under two names, and both report hekma 0.11.0 for --version. Use whichever you like.

Do I need to register my agents again? No. Hekma opens the same state directory, and your fleet is exactly as you left it.

Is it safe to keep the old kt? Yes. It stays at its last version and can no longer update. The installer never deletes it; it tells you where it is and how to remove it. Hekma upgrades the state database to its newer format the first time it opens it, and an older kt refuses a database written by a newer version, so once you have run hekma, use it instead of kt.

Do my scripts need changes? Replace kt with hekma. JSON formats and exit codes are the same, and the old environment variables still work. Some Hekma 0.11.0 messages still mention kt agent … in their suggested fix; type hekma agent … instead.

What happened to the ktesio crate? It stays on crates.io at 0.7.0, so old lockfiles still build, but it gets no new versions.

  • Install: every install method, updating and uninstalling.
  • Quickstart: a five-minute tour of Hekma.
  • Release notes: what changed in each release since the rename.