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.

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        Pull new pages from the server into .contexo/
  push        Push local .contexo pages to the server
  remote      Configure the Contexo server URL and repo ID
  status      Show .contexo status and local-vs-server delta
  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

Five variables change what ctx does. Everything else the CLI needs — server URL, repo ID, auth token — comes from .contexo/config.json and .contexo/credentials.json, 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 mcp (ctx_push)	exactly 1	Skips the distill handshake, so a push of concept/analysis pages uploads directly instead of first asking the agent to write a source page. Same effect as passing no_distill: true on every call.
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_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

The first three are compared against the exact string 1. CONTEXO_DRIFT_DISABLE=true and CONTEXO_CAPTURE_DISABLE=yes do nothing. The last two 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 are read by 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 five, 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.

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
• Self-hosting guide — running contexo-server with the variables above