ctx self-update

Update the ctx binary from GitHub releases — explicitly, never automatically.

Synopsis

ctx self-update [--version <X.Y.Z>] [--json]
ctx --version --check

Description

ctx self-update queries the GitHub Releases API for agentis-tools/ctx, downloads the artifact for the current platform, verifies it, and atomically replaces the running executable:

1. Fetch the latest release (or the release pinned with --version X.Y.Z).
2. Pick the artifact matching this binary's compile-time target (ctx-<tag>-<target>.tar.gz, .zip on Windows).
3. Download the release's aggregated SHA256SUMS file and the artifact, and verify the artifact's sha256 against it. On mismatch the update aborts with exit code 2 and the installed binary is untouched.
4. Extract the ctx binary, write it to a temp file in the same directory as the current executable, set executable permissions, and rename it over the current binary (atomic on the same filesystem).

If nothing newer exists, it prints ctx <version> is already up to date and exits 0. On success it prints the transition:

ctx 0.2.1 → 0.3.0

--version X.Y.Z installs that exact release — including downgrades — instead of the latest.

Before any network work, ctx verifies the install location is writable; if not (e.g. a system-wide install), it refuses with guidance (exit 2). If ctx was installed with cargo, prefer cargo install agentis-ctx.

On Windows the running ctx.exe cannot be overwritten directly, so it is renamed aside to ctx.exe.old first; the .old file is removed on the next ctx self-update (or can be deleted manually).

Prebuilt artifacts exist for x86_64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin, and x86_64-pc-windows-msvc — the release workflow's build matrix. On other platforms self-update exits 2 and points at cargo install agentis-ctx.

The passive update notice

On interactive invocations, ctx checks for a newer release at most once per 24 hours (timestamp cache under your user cache directory, e.g. ~/.cache/ctx/ or ~/Library/Caches/ctx/), with a 1-second network timeout and silent failure. When a newer release exists it prints exactly one line to stderr:

ctx 0.3.0 available (you have 0.2.1) — run 'ctx self-update'

Determinism rule: ctx never updates itself automatically. The passive check only prints this notice; installing anything always requires an explicit ctx self-update.

The check is completely skipped — no network call at all — when any of these hold:

• CTX_NO_UPDATE_CHECK=1 is set;
• stderr is not a terminal (pipes, CI, test harnesses);
• --json is active (stdout must stay a single JSON document; the notice never reaches stdout either way);
• ctx is running inside a Claude Code hook or session (CLAUDECODE, CLAUDE_PROJECT_DIR, or CLAUDE_PLUGIN_ROOT in the environment);
• the invocation is ctx self-update or ctx --version itself.

ctx --version --check

An explicit, always-allowed comparison against the latest release — exempt from the suppression rules and the 24h cache. It prints its result to stdout (it is the primary output, not a notice) and exits 0 whether or not an update exists:

$ ctx --version --check
ctx 0.3.0 available (you have 0.2.1) — run 'ctx self-update'
# or
ctx 0.2.1 is up to date

Plain ctx --version (or -V) is unchanged: it prints ctx <version> and never touches the network.

Updating the Claude Code plugin

The plugin generated by ctx harness init --mode plugin is versioned in lockstep with the binary (its plugin.json version is the generating crate version, asserted by the release pipeline). Update the plugin through Claude Code's own mechanism:

/plugin update ctx

then update the binary with ctx self-update and re-run ctx harness init --mode plugin if you maintain the scaffold yourself. To freeze an install, pin the marketplace entry to a commit SHA:

/plugin marketplace add agentis-tools/ctx@<commit-sha>

Note that harness permissions generated by ctx harness init deny Bash(ctx self-update*), so an AI agent cannot swap the binary out from under a running session.

JSON output

ctx self-update --json emits the standard envelope with command self_update:

{
  "ctx_version": "0.2.1",
  "command": "self_update",
  "generated_at": "2026-07-09T12:00:00Z",
  "data": {
    "old_version": "0.2.1",
    "new_version": "0.3.0",
    "outcome": "updated"
  }
}

outcome is updated or up_to_date. ctx --version --check --json emits command version.check with current_version, latest_version, and update_available. See JSON Output.

Exit Codes

Code	Meaning
0	Updated successfully, or already up to date
2	Operational error (network failure, checksum mismatch, install location not writable, unsupported platform, unknown version)

Examples

ctx self-update                    # update to the latest release
ctx self-update --version 0.3.0    # install an exact release (downgrades allowed)
ctx self-update --json             # machine-readable result
ctx --version --check              # just compare, never install
CTX_NO_UPDATE_CHECK=1 ctx map      # silence the passive notice for one run