ctx status

ctx status prints how this project is wired up — server, repo, identity — plus how the local knowledge base compares to the server’s.

When you’d reach for it

It’s the first thing to run when something isn’t syncing: the top half answers “is this project actually pointed at anything?” and the bottom half answers “what’s out of step?”. Run it before a first push in an unfamiliar checkout, and after a teammate says they pushed.

Status writes nothing, but it isn’t free — the drift check makes one HTTP request per locally-tracked page, so on a large knowledge base it is the slow part. --no-drift gives you the configuration summary instantly and works offline.

Synopsis

ctx status
ctx status --no-drift

Flags

Flag	Type	Default	Description
--no-drift	bool	false	skip the per-page server-drift check (faster; offline-friendly)

The drift check is skipped automatically — no flag needed — when you’re unauthenticated, or when server_url or repo_id is missing from .contexo/config.json. In those cases the Pages drifted on server: line simply doesn’t appear.

Note

CONTEXO_DRIFT_DISABLE=1 does not affect this command. That variable suppresses the DRIFT_NOTICE block the MCP server prepends when an agent reads a page. The CLI’s own drift check is controlled only by --no-drift.

ctx status also accepts the global flag:

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

What each line means

Not initialized (run 'ctx init') — there’s no .contexo/ directory here. Status stops there and exits 0; nothing else is printed.

Initialized: yes — .contexo/ exists.

Server: — server_url from .contexo/config.json, or (none — run 'ctx remote set <url>').

Repo: — repo_id from the same file, or (none — run 'ctx remote set-repo <id>'). This is the repo on the server your pushes and pulls talk to.

Authenticated: — yes plus the shape of the stored token: personal access token (ctxp_…), session token (a JWT, from the browser login), legacy API key (anything else), or invite key (NOT for CLI use) if a ctxi_… key ended up in credentials by mistake — that one needs ctx join, not ctx login.

User: — the name and email stored at login, only printed when a name is present. These are what the server records as the git author on your commits.

Local pages: — parseable Contexo pages found by walking .contexo/. Dot-directories, index.md, tags.md and files whose frontmatter doesn’t parse are not counted. “Parse” here means the --- block is present, closed, and valid YAML — required keys are not checked at this point, so a page missing author or type still counts, and still gets pushed.

Last pull: — the short last_pull_sha from .contexo/.sync/state.json, or (never). Pushing does not update it, so (never) next to a healthy push history is normal.

Pages never pushed: — pages with no recorded sha in .contexo/.sync/state.json. Both push and pull record shas, so this counts pages the server has never seen from this machine. It is also exactly the set of pages that would overwrite the server copy without a conflict check.

Pages drifted on server: — pages whose server sha no longer matches the one you recorded. With none, the line reads exactly Pages drifted on server: 0; with any, it becomes Pages drifted on server (run `ctx pull` to refresh): N followed by one indented line each, <path> (local <sha> → server <sha>). These are the pages that will 409 on your next push.

Examples

Before ctx init has run:

ctx status

ctx status (no .contexo/)

Not initialized (run 'ctx init')

Freshly initialised, nothing configured yet. Note there’s no drift line: with no server, repo or credentials there’s nothing to check against.

ctx status

ctx status (fresh init)

Initialized: yes
Server: (none — run 'ctx remote set <url>')
Repo: (none — run 'ctx remote set-repo <id>')
Authenticated: no
Local pages: 0
Last pull: (never)
Pages never pushed: 0

Fully wired up, one page pushed. Last pull: (never) is expected here — the page went up, nothing has come down:

ctx status

ctx status (after a push)

Initialized: yes
Server: https://contexo.example.com
Repo: acme-api
Authenticated: yes (legacy API key)
User: dev <dev@example.com>
Local pages: 1
Last pull: (never)
Pages never pushed: 0
Pages drifted on server: 0

How it works

The configuration lines are pure local file reads: .contexo/config.json, .contexo/credentials.json, .contexo/.sync/state.json, plus a walk of .contexo/ to count pages. Nothing is written.

The drift check, when it runs, issues one GET /v1/repos/<repo>/pages/<path> per locally-tracked page and compares the X-Page-SHA response header to the sha in state.json. Pages with no recorded sha are skipped — drift needs a baseline, so a page you authored locally and never pushed can’t be “drifted”. Per-page errors are swallowed silently: an unreachable server produces Pages drifted on server: 0, not a failure. Treat a zero as “no drift detected”, not “definitely in sync”.

Caution

The Server: line reads config.json, but ctx push, ctx pull and ctx log prefer the server_url stored in credentials.json when it’s set. ctx login writes both, so they normally agree — but ctx remote set <url> only updates config.json. After changing servers that way, status will show the new URL while sync still talks to the old one. Re-run ctx login --server <url> to move both.

See also

• ctx push — what to do about never-pushed pages
• ctx pull — what to do about drifted ones
• ctx remote — set the server URL and repo id the top half reports
• Drift and conflicts — the mechanics behind the drift line