Skip to content
ContexoContexo Docs

ctx version

ctx version prints the identity that was stamped into this binary at build time: the release version, the short git commit it was built from, and the build date.

When you’d reach for it

Section titled “When you’d reach for it”

Three situations. You’re filing a bug or comparing notes with a teammate and need the exact build, in which case you want the full line with the commit. Or you’re scripting — a setup script that enforces a floor version, a CI job that records the toolchain — in which case --short gives you the bare number and nothing to parse around. Or a program needs to know what this ctx can do before it drives it, which is what --json is for: the VS Code extension runs ctx version --json before anything else, to check that this ctx speaks its contract.

It is also the fastest way to tell whether self-update will work at all: a binary that reports dev was built with go build/go install, has no release stamp, and ctx update will refuse to touch it.

Synopsis

Section titled “Synopsis”
Terminal window
ctx version
ctx version --short
ctx version --json
ctx --version      # root flag; version number only

Flags

Section titled “Flags”
FlagTypeDefaultDescription
--jsonboolfalseprint the ctx.version.v1 handshake document (contract version and capabilities)
--shortboolfalseprint just the version number
FlagTypeDefaultDescription
--rootstringproject root directory (default: current directory)

--root is inherited from the root command and has no effect here: ctx version reads no project files.

Examples

Section titled “Examples”

The full identity line — what to paste into a bug report:

Terminal window
ctx version
ctx version
ctx 0.7.0 (9f31c07, 2026-07-28)

Just the number, for scripts:

Terminal window
ctx version --short
ctx version --short
0.7.0

The handshake document, for programs:

Terminal window
ctx version --json
ctx version --json
{
  "schema": "ctx.version.v1",
  "contract_version": 1,
  "version": "0.7.0",
  "commit": "9f31c07",
  "date": "2026-07-28",
  "dev_build": false,
  "os": "darwin",
  "arch": "arm64",
  "capabilities": [
    "status.json",
    "status.offline",
    "show.base",
    "show.server",
    "show.sha",
    "pull.json",
    "push.json",
    "push.paths",
    "push.distill_guard",
    "resolve",
    "errors.envelope",
    "repair"
  ]
}

contract_version is the version of the machine contract this ctx speaks (1). capabilities lists what this build can do, in a fixed order: the eleven version 1 capabilities, then the optional repair. A caller checks that the capabilities it needs are present rather than comparing version numbers. commit and date are the same short commit and build date as the human line; dev_build is true for an unstamped build, and os and arch name the platform the binary was built for. JSON output and exit codes lists every capability and what it means.

How it works

Section titled “How it works”

The three values come from package-level variables overridden at release build time with -ldflags -X …/internal/version.Version=…, .Commit=… and .Date=…. Nothing is read from disk, no config is loaded, and no network request is made — which is why this command works outside a Contexo project.

An un-stamped build falls back to the defaults dev, none and unknown, in that order, and IsDevBuild() — the predicate ctx update and the background update nudge both consult — is exactly the test Version == "dev".

--json writes the document and nothing else, and like --short it runs in machine mode: no colour and no update nudge.

ctx --version (or -v) is a different code path: it’s cobra’s built-in version flag on the root command, rendering ctx version <number> from the same Version variable, without the commit or date. Use the subcommand when you care about provenance.

See also

Section titled “See also”