Updating and uninstalling

Updating

ctx update --check     # look, don't touch
ctx update             # download, verify, replace in place

ctx update --check

Current version: 0.5.1
Checking for updates…
You're already on the latest version (0.5.1).

Version comparison is major/minor/patch only — a pre-release or build suffix (-rc.1, +build3) is stripped before comparing, and a tag that won’t parse is treated as “not newer” so a malformed release can never nag you into installing it.

Two cases short-circuit before any network call:

• Dev builds. A binary with no version stamp (go run, go build without ldflags) can’t self-update; ctx update says so and points at go install github.com/sugihAF/contexo/cmd/ctx@latest.
• Package-manager installs. The path of the running executable is inspected: anything under /Cellar/, /homebrew/ or /linuxbrew/ is redirected to brew upgrade contexo, anything under /scoop/ to scoop update ctx, so the manager’s bookkeeping stays consistent. Everything else is treated as a managed install and is safe to replace. (Neither channel is published yet — the redirect is there so a future brew or scoop install never gets clobbered by a self-replace.)

Flag	Type	Default	Description
--check	bool	false	only check for a newer version; don't install

How a release is verified

The updater refuses to return anything it could not verify:

1. Fetch the latest release from the GitHub API for sugihAF/Contexo.
2. Pick the asset matching your platform by name — ctx_<version>_<os>_<arch>.tar.gz, or .zip on Windows. No asset, no update.
3. Download checksums.txt from the same release. If the release has no checksums.txt, the update aborts rather than installing an unverified binary.
4. Compare the archive’s SHA-256 against the line for that asset. A missing line is a failure, not a pass.
5. Extract ctx (ctx.exe on Windows) from the archive and swap it atomically over the running executable — including the rename dance Windows requires — rolling the old binary back if the swap fails.

Signature verification is wired but not yet armed. When a minisign public key is pinned into the build, a release without a valid checksums.txt.minisig is refused outright, so write access to GitHub Releases alone would no longer be enough to ship a trojaned binary. Today’s releases ship unsigned, so the guarantee you actually get is checksum integrity against the release GitHub served you. scripts/install.sh is close but not identical: it always enforces the checksum, and checks the signature only when CONTEXO_MINISIGN_PUBKEY is set — and even then it warns and continues if the minisign binary isn’t installed, where the Go updater fails closed.

The update nudge

After a successful interactive command, ctx prints a single dim line to stderr when a newer version exists:

✨ ctx 0.6.0 available (you have 0.5.1) — run `ctx update`

It checks GitHub at most once every 24 hours, caching the result in <user cache dir>/contexo/update-check.json, with a 1.5-second timeout and every error swallowed — it can never affect the command you actually ran. It stays quiet when stdout isn’t a terminal, on dev builds, when CI or CONTEXO_NO_UPDATE_CHECK is set, and for ctx mcp, ctx capture, ctx version and ctx update (the first two produce machine-read output that a stray line would corrupt).

Reinstalling instead

The install scripts are idempotent, so re-running one is a legitimate way to update — including on a dev build, where ctx update refuses to self-replace.

curl -fsSL https://raw.githubusercontent.com/sugihAF/Contexo/main/scripts/install.sh | sh

iwr -useb https://raw.githubusercontent.com/sugihAF/Contexo/main/scripts/install.ps1 | iex

Defaults: $HOME/.local/bin on Linux/macOS (override with CONTEXO_INSTALL_DIR), %LOCALAPPDATA%\Programs\contexo on Windows. Both add that directory to your PATH if it isn’t already there, and both warn if a different ctx already shadows the one they installed.

Removing Contexo from a project

ctx detach is the inverse of ctx init. It reverses the wiring, and by default also deletes the knowledge:

ctx detach --keep-knowledge

This will:
  - delete .mcp.json (only contained the contexo entry)
  - delete .cursor/mcp.json (only contained the contexo entry)
  - remove the .contexo/ line from .gitignore
  - remove the Contexo Stop hook from .claude/settings.json
  - remove the Contexo capture hooks from .cursor/hooks.json
  - (keeping .contexo/ as requested)
Proceed? [y/N] Aborted.

It prints the plan first, then asks. Depending on what ctx init actually did, the plan covers:

• the contexo entry in ./.mcp.json (Claude Code) — deleting the file when that entry was all it held, editing it in place otherwise, so other MCP servers survive
• the same for ./.cursor/mcp.json (Cursor)
• Codex’s global entry in ~/.codex/config.toml, via codex mcp remove contexo, but only when Codex is installed and actually wired
• the .contexo/ line in .gitignore (and the comment header init wrote above it)
• the Claude Code Stop hook in .claude/settings.json
• the capture hooks in .codex/hooks.json and .cursor/hooks.json
• .contexo/ itself — unless you pass --keep-knowledge

Flag	Type	Default	Description
--keep-knowledge	bool	false	keep the .contexo/ directory; only remove the wiring (MCP entries, .gitignore line, Stop hook)
--yes, -y	bool	false	skip the confirmation prompt

Caution

The default deletes .contexo/, including pages you never pushed. Detach counts them first and warns before asking:

  - DELETE the .contexo/ directory and everything in it
    ! WARNING: 3 local page(s) have never been pushed to the server.
    ! Run `ctx push` first, or re-run with --keep-knowledge to preserve them.

Pages that were pushed still live in the server’s git history — detaching a project doesn’t touch the server.

Use --keep-knowledge when you only want the agent integration gone: the MCP entries and hooks are removed, .contexo/ stays, and ctx init later re-wires everything against the pages that are still there.

Full uninstall

Contexo keeps state in three places: per-project directories, the binary, and one cache file.

1. Per project — run ctx detach --yes in each project that has .contexo/ (or delete the directory and the MCP/hook files by hand). This also removes Codex’s global MCP entry if it was wired.

2. The binary

   rm ~/.local/bin/ctx                 # or $CONTEXO_INSTALL_DIR/ctx

   Remove-Item "$env:LOCALAPPDATA\Programs\contexo\ctx.exe"

   Homebrew: brew uninstall contexo. Scoop: scoop uninstall ctx.

3. The PATH line the installer appended — # Added by Contexo installer in ~/.zshrc, ~/.bashrc, ~/.bash_profile or ~/.config/fish/config.fish. On Windows, remove the install directory from your user Path.

4. The update-check cache

   Platform	Path
   Linux	~/.cache/contexo/update-check.json
   macOS	~/Library/Caches/contexo/update-check.json
   Windows	%LOCALAPPDATA%\contexo\update-check.json

Credentials are per project, not global: the token lives in .contexo/credentials.json, so removing .contexo/ removes it. If that token was a personal access token you’d rather not leave valid, revoke it on the server side as well — deleting the local copy doesn’t.

Related

• ctx update · ctx detach · ctx version
• Install — first-time setup
• Connect your agent — what ctx init wires up