AkurAI-Framework / site/content/docs/updating.md

Latest change 802bc0c4c24b7a3a3474557988d3e930b2422c3f - feat(cli): add 'akurai update' self-update subcommand by Ólafur Búi Ólafsson

# Updating the CLI

The `akurai` binary can update itself in place from the latest GitHub release.

```sh
akurai update          # download and install the latest release if newer
akurai update --check  # only report whether an update is available
```

Aliases: `akurai upgrade` and `akurai self-update` behave identically to
`akurai update`.

## What it does

1. Reads the running binary's version (`CARGO_PKG_VERSION`, baked in at build).
2. Queries the latest release of `olibuijr/AkurAI-Framework` from the GitHub
   API and reads `tag_name` (a leading `v` is stripped, so `v0.4.2` → `0.4.2`).
3. Compares current vs. latest with a numeric, semver-ish comparison: each
   dotted component is parsed as a number and compared in order; missing
   components count as zero, so `0.1` and `0.1.0` are equal.
4. `--check` stops here and just reports the result.
5. Without `--check`, if the latest version is newer, it downloads the matching
   platform asset and replaces the running binary.

If you are already current, it prints
`akurai: already on the latest version (<v>)` and exits 0.

## Asset naming convention

Release assets follow `akurai-<os>-<arch>`, matching `install.sh`:

| OS    | `<os>`  |
| ----- | ------- |
| Linux | `linux` |
| macOS | `macos` |

| Arch    | `<arch>`  |
| ------- | --------- |
| x86_64  | `x86_64`  |
| aarch64 | `aarch64` |

So a 64-bit Intel/AMD Linux build downloads `akurai-linux-x86_64`, and an Apple
Silicon Mac downloads `akurai-macos-aarch64`. Any other platform is unsupported
and the command errors clearly, pointing you to a source install.

## How the atomic self-replace works

The new binary is downloaded to a sibling `*.new` file **next to the current
executable** (located via `std::env::current_exe()`), never `/tmp`. Keeping it
on the same filesystem means the final swap is a same-device `rename`, not a
cross-device copy.

After download the file is marked executable (`chmod 0755`) and then `rename`d
over the running binary. On Linux and macOS this is atomic and safe even while
the CLI is running: the live process keeps its original inode open, and the
replacement takes effect on the next launch. If anything fails — a failed
download, a permission error on the swap — the existing binary is left
untouched and the partial download is removed.

## The curl dependency

The framework links **no external crates**, and the Rust standard library has
no HTTPS client. So network I/O shells out to the system `curl` binary via
`std::process::Command` — the same approach `install.sh` uses. `curl` is a
system tool, not a linked dependency, so the zero-dependency promise holds.
Make sure `curl` is installed and on your `PATH`.

## Permissions

If the binary lives somewhere only root can write (e.g. `/usr/local/bin`), the
swap fails with a permission error. Re-run with the right permissions
(`sudo akurai update`) or reinstall via `install.sh`.

## Caveat: requires a public repo with a published release

Self-update only works once `olibuijr/AkurAI-Framework` is **public** and a
release has been **published**. The repository is currently private, so until a
release is cut the GitHub API returns 404 and `akurai update` reports
"no release found" and exits non-zero **without writing anything**.