Global flags and environment

Everything on this page applies across the CLI: one persistent flag, two cobra conventions, and a short list of environment variables that change behaviour. For --json, the error envelope and exit codes, see JSON output and exit codes.

Persistent flags

Flag	Type	Default	Description
--root	string	—	project root directory (default: current directory)

--root is declared on the root command, so it appears in every command’s --help and can be placed anywhere on the line. It names the project directory that contains .contexo/ — not the .contexo/ directory itself:

ctx status --root ~/work/acme-api
ctx migrate --root ~/work/acme-api --list

This matters more than it looks, because ctx does not search upward for a project. Run a project command from a subdirectory and you get an error telling you to run ctx init, even though the project exists two levels up. Either cd to the root or pass --root. (The one exception is the hidden ctx capture turn, which agent hooks invoke from wherever the agent happens to be; it walks up from its working directory to find .contexo/. See ctx capture.)

Commands that touch nothing on disk — ctx version, ctx update — accept --root and ignore it.

--help and --version

-h/--help is added by cobra to every command and subcommand, and ctx help <command> is equivalent. The help text you get is the same string this reference renders its flag tables from, so the two can’t drift:

ctx --help
ctx push --help
ctx mcp install --help

ctx --help

ctx manages a per-project knowledge base of distilled AI sessions and syncs it with a Contexo server so teammates' agents start from the same context.

Usage:
  ctx [command]

Available Commands:
  activity    Show recent push/pull activity on the current repo
  auth        Authentication management
  capture     Capture utilities for the agent-reasoning buffer
  completion  Generate the autocompletion script for the specified shell
  detach      Reverse `ctx init` — remove Contexo wiring (and, by default, the .contexo/ directory)
  diff        Show the structured diff between two versions of a page
  evolution   Show the full evolution of a page: each commit + what it changed
  generate    Seed a Contexo knowledge base from the codebase (via Graphify)
  help        Help about any command
  history     Show the commit timeline for a single page
  hooks       Manage the Contexo capture hook (Claude Code, Codex)
  init        Initialize .contexo knowledge directory
  invite      Manage repo invite keys
  join        Join an existing Contexo repo using an invite key
  log         Show the server's commit timeline (who changed what when)
  login       Authenticate with a Contexo server (alias for `ctx auth login`)
  mcp         Run the MCP server over stdio against the local .contexo/
  members     List and manage who can access the current repo
  migrate     Bulk-import an existing knowledge base into Contexo
  pull        Safely pull teammates' page changes into .contexo/
  push        Push changed local .contexo pages to the server
  remote      Configure the Contexo server URL and repo ID
  repair      Backfill missing base snapshots and fix wrong page shas
  resolve     Resolve a conflict by keeping the local or the server version
  show        Print a page's base, server or historical bytes
  status      Show each page's local, base and server state
  update      Update ctx to the latest release
  version     Print the ctx version

Flags:
  -h, --help          help for ctx
      --root string   project root directory (default: current directory)
  -v, --version       version for ctx

Use "ctx [command] --help" for more information about a command.

-v/--version exists only on the root command and prints ctx version <number> — no commit, no build date. For the full build identity use ctx version, which also has --short for scripts.

Environment variables

These variables change what ctx does. Everything else the CLI needs — server URL, repo ID, auth token — comes from .contexo/config.json and the credentials files, and has no environment override.

Variable	Read by	Accepted value	Effect
CONTEXO_CAPTURE_DISABLE	ctx capture turn	exactly 1	The hook target returns immediately. Agent turns stop being appended to the capture buffer, without you having to uninstall the hooks.
CONTEXO_DISTILL_DISABLE	ctx push, ctx mcp (ctx_push), ctx status	exactly 1	Turns off the distill guard. ctx push sends concept/analysis pages even while an agent session is pending (like --no-distill), and ctx_push uploads directly instead of first asking the agent to write a source page (like no_distill: true). The push document records distill.bypassed: true, and ctx status stops reporting that captures block a push. The VS Code extension removes this variable from the environment it runs ctx with, so it never bypasses the guard.
CONTEXO_DRIFT_DISABLE	ctx mcp (page reads)	exactly 1	Suppresses the drift notice that is prepended when the server’s copy of a page has moved on from yours, and with it the server lookup behind the notice (otherwise one read per page, cached for 60 seconds).
CONTEXO_CLIENT	every command that talks to the server	any value without control characters	Sent as the X-Contexo-Client header on every request, which the server records in the repo’s activity. Precedence: this variable, then the name the program set for itself (under ctx mcp, the agent’s MCP client name, else ctx-mcp), then ctx-cli. The VS Code extension sets contexo-vscode/<version>.
CONTEXO_LOCK_TIMEOUT	ctx push, pull, resolve, repair	a Go duration (3s, 1m) or whole seconds (7)	How long to wait for .contexo/.sync/lock when another ctx process holds it, before failing with busy (exit 12 with --json). Default 10 seconds; an unparseable or negative value means the default.
CONTEXO_NO_UPDATE_CHECK	every command	any non-empty value	Disables the background “update available” nudge.
CI	every command	any non-empty value	Same as above — the nudge assumes any CI environment wants silence.

The comparison is literal

CONTEXO_CAPTURE_DISABLE, CONTEXO_DISTILL_DISABLE and CONTEXO_DRIFT_DISABLE are compared against the exact string 1. CONTEXO_DRIFT_DISABLE=true and CONTEXO_CAPTURE_DISABLE=yes do nothing. CONTEXO_NO_UPDATE_CHECK and CI only test for non-emptiness, so CONTEXO_NO_UPDATE_CHECK=0 does disable the nudge. Set the first three to 1 and treat the last two as on/unset.

Setting variables for the MCP server

CONTEXO_DRIFT_DISABLE and CONTEXO_DISTILL_DISABLE also matter to the process running ctx mcp — and that process is launched by your coding agent, not by your shell. Exporting them in a terminal has no effect on an agent that is already running. Set them in the environment the agent itself inherits, or add an env entry to the MCP server block in your agent’s config (ctx mcp install writes the command and args; the env key is yours to add), then restart the agent.

Beyond those variables, the update nudge writes a cache file at update-check.json inside your OS cache directory — %LocalAppData%\contexo\ on Windows, ~/Library/Caches/contexo/ on macOS, ~/.cache/contexo/ (or $XDG_CACHE_HOME/contexo/) on Linux. Deleting it just forces the next check to go to the network.

Interrupting ctx

A few commands show a spinner while they wait: the browser login of ctx auth login, ctx generate, ctx migrate and ctx update. If you press Ctrl+C while a spinner is up, ctx first stops the spinner and restores the terminal (the cursor and bracketed paste mode), then ends itself with SIGINT, the same way Ctrl+C ends any other program. The shell or script that ran it sees a process killed by SIGINT and stops too, instead of carrying on with the next command. On Windows, where a process cannot signal itself, ctx exits with status 130 instead.

Commands without a spinner, ctx push and ctx pull among them, end at once on Ctrl+C, the default behaviour. Their state files are each written atomically, and a sync lock left behind by a process that no longer runs is reclaimed by the next ctx command on the same machine.

Self-hosted server variables

These are read by the contexo-server binary, not by ctx. Setting them in your CLI shell does nothing; they belong in the server’s environment or unit file.

Variable	Default	Effect
PORT	8080	Port used to build the listen address when CONTEXO_LISTEN_ADDR is unset.
CONTEXO_LISTEN_ADDR	:$PORT	Full listen address. Set 127.0.0.1:8080 to bind loopback only and let a reverse proxy be the sole ingress.
CONTEXO_DATA_ROOT	./contexo-data	Directory holding the per-project git repos and the contexo.db SQLite database (users, tokens, members, invites, activity). Created if missing.
CONTEXO_SESSION_SECRET	random per boot	Signing key for session tokens. Unset means every restart invalidates existing sessions, and the server logs a warning.
GOOGLE_OAUTH_CLIENT_ID	unset	Enables Google sign-in. While unset, POST /v1/auth/google returns 503.
CONTEXO_API_KEY	dev-key	The legacy shared-secret key accepted alongside real tokens. Change it on anything reachable from a network.
CONTEXO_CORS_ORIGINS	http://localhost:5173,http://localhost:3000	Comma-separated browser origins allowed to call the API. * allows any origin.
CONTEXO_TRUSTED_PROXIES	127.0.0.1,::1	Comma-separated proxy addresses whose X-Forwarded-For is trusted for client-IP derivation (and therefore rate limiting).
CONTEXO_MAX_BODY_BYTES	8388608 (8 MiB)	Request body cap.
CONTEXO_RATELIMIT_PER_MIN	300	General per-IP request rate.
CONTEXO_RATELIMIT_BURST	100	General per-IP burst.
CONTEXO_AUTH_RATELIMIT_PER_MIN	15	Rate for POST /v1/auth/google.
CONTEXO_AUTH_RATELIMIT_BURST	8	Burst for the same endpoint.
CONTEXO_RATELIMIT_DISABLE	unset	1, true or yes removes the per-IP limiters entirely.

Note

The numeric variables are parsed leniently: a value that isn’t a positive integer is ignored and the default applies, with no warning. CONTEXO_RATELIMIT_DISABLE is the one variable in the whole system that accepts true/yes as well as 1 — the CLI-side switches above do not.

See also

• ctx version — the build identity behind --version
• ctx update — the nudge that CONTEXO_NO_UPDATE_CHECK silences
• ctx mcp — where to put the MCP-side environment variables
• JSON output and exit codes — --json, the error envelope, every exit code and CONTEXO_CLIENT
• Self-hosting guide — running contexo-server with the variables above