ctxhub

The ctxhub command-line tool — bind a repository to a ctxhub context drive, then read, lint, and open that binding from your terminal or CI.

A ctxhub drive is the shared knowledge base your team (and your agents) read and write. A repo "binding" is a small file (.ctxhub/repo.yaml) that points a checkout at one drive so every tool — editors, agents, CI — sees the same context.

Install

npm install -g @ctxhub/cli
# or run on demand
npx @ctxhub/cli --help

Requires Node.js 20+.

Quick start

# Sign in (opens your browser; no local listener needed).
ctxhub login

# Bind the current repo to a drive.
ctxhub bind @acme/engineering

# Inspect the binding.
ctxhub repo

# Open the drive in your browser.
ctxhub open

# Check the binding is healthy (use this in CI).
ctxhub check

ctxhub bind writes .ctxhub/repo.yaml locally and adds the repo's origin URL to the drive's repos: list. Pass --no-sync to skip the drive-side update (the local file is always written).

To point the CLI at a different host (self-hosted, staging, dev), set CTXHUB_SERVER or pass --server <url> to login / logout.

Commands

| Command | What it does | | --------------- | --------------------------------------------------------------------------- | | init | Interactive setup — pick or create a drive and write .ctxhub/repo.yaml. | | bind <h>/<s> | Non-interactive bind to @handle/slug. Use --module for monorepos. | | repo | Pretty-print the current binding. --json for machine output. | | open | Open the bound drive in your browser. --print prints the URL instead. | | doctor | Verify the binding is consistent with what the drive knows. --fix repairs drift. | | check | Lint the binding. Emits healthy, missing, drifted, or broken. | | login | Sign in via the OAuth device flow. Opens your browser to confirm a code. | | logout | Revoke cached tokens and clear local credentials. |

Run ctxhub <command> --help for full flags.

Full API surface

In addition to the repo/drive binding verbs above, ctxhub exposes every user-facing /api/* route under a typed verb tree. Each verb returns the API's JSON shape as-is under --json and prints pretty JSON by default. Streaming endpoints (chats stream, jobs stream) emit NDJSON when --json is set.

# auth: use the existing OAuth login or set CTXHUB_TOKEN for CI
ctxhub login
export CTXHUB_TOKEN=$(ctxhub me pats create --name ci --ttl 90 \
  --scope drive:read,drive:write --json | jq -r .secret)

Verb cheatsheet

| Namespace | Verbs | | --------------------- | ---------------------------------------------------------------------------------------------------- | | account | get, update, getting-started, getting-started update | | activity | list | | agent-suggestions | list, refresh | | agents | list, get, create, update, delete, run, draft, runs list/get, triggers list/create/update/delete | | api-version | get | | atlas | get, clusters, concept, search, refresh | | banner | get | | billing | checkout, portal | | chats | list, get, send, update, delete, cancel, extract, extract-knowledge, recipients, stream | | drive-templates | list | | drives | list, get, create, update, delete, current, by-handle, repos add/remove, github open-pr/repo-yaml, invitations list/create, links create/delete, members add/remove, memory-types list/create/update/delete/apply-preset/draft | | files | list, get, create, update, replace, delete, download, duplicate, move, references, reindex, comments, comment, import | | integrations | list, capabilities, setup, github connect-many, github install start, slack oauth start | | invitations | get, delete, accept, decline, reinvite, claim | | jobs | active, get, events, stream | | knowledge | list, get, create, update, delete, invoke-action, remediate | | leads | create | | me | handle, cli hello/status/whoami, drives, invitations, pats list/create/update/delete | | memory-types | list (platform templates) | | observability | get | | ops | flag-resolve, flag-pref-get/set/clear, slack-disconnect | | orgs | list, get, create, update, delete, overview, auto-join, members, member-set/remove, invite-bulk/resend, integrations github/slack, drive-templates list/create/update/delete | | p | get-drive, list-files, get-file (public-read surface) | | search | query | | sessions | list, end | | skills | list, get, create, update, delete, draft | | sources | get, update, delete, connect, streams, streams create/delete | | users | search | | raw | <METHOD> <path> — escape hatch for routes the typed surface skips |

Get the full verb list for a namespace with ctxhub <namespace> -h, and the full per-verb help with ctxhub <namespace> <verb> -h.

Destructive verbs (any DELETE) require an explicit --yes.

API verb exit codes

| Code | Meaning | | ---- | ------------ | | 0 | success | | 1 | user error | | 2 | auth (401/403, no token) | | 3 | not found (404) | | 4 | server error (>=500) / network failure | | 5 | conflict (409) |

(The original repo/drive binding verbs — init, bind, repo, ... — retain their separate exit-code map; see below.)

ctxhub raw

When you need a route the typed surface doesn't cover:

ctxhub raw GET /api/me/drives
ctxhub raw POST /api/chats --body '{"driveId":"d1","message":"hi"}'
ctxhub raw GET /api/jobs/stream --stream
ctxhub raw POST /api/files/import --body @import.json

--body @- reads stdin; --body @<path> reads a file; otherwise the argument is treated as inline JSON (and falls back to a plain string).

Global flags

| Flag | Meaning | | -------------- | -------------------------------------------------------- | | --json | Emit a single JSON object on stdout. | | --no-color | Disable ANSI color (also honors NO_COLOR). | | --cwd <path> | Run as if invoked from <path>. | | --quiet | Suppress progress output. | | --verbose | Debug logs on stderr. | | -h, --help | Show help (top-level or per-command). | | --token <t> | Bearer token (or env CTXHUB_TOKEN). | | --server <u> | Server URL override (or env CTXHUB_SERVER). | | --version | Print the CLI version. |

Exit codes (repo/drive binding verbs)

| Code | Meaning | | ---- | ------------------------------------------------------------- | | 0 | Success. | | 1 | Soft failure — binding missing, drifted, or user cancelled. | | 2 | Hard failure — invalid file, broken binding, IO error. | | 3 | Authentication required — run ctxhub login. | | 4 | Network error. | | 64 | Usage error. |

ctxhub check --require collapses every non-healthy result to exit 2, which is the shape you typically want in CI.

CI example

- name: Verify ctxhub binding
  run: npx -y @ctxhub/cli check --require

Telemetry

The CLI ships with telemetry off by default. Opt in with:

ctxhub --telemetry on
ctxhub --telemetry off    # opt back out at any time

When enabled, each invocation emits one event with the subcommand name, exit code, duration, OS, and a random anonymous id. No arguments, paths, drive handles, or repo URLs are collected. The state lives at ~/.config/ctxhub/telemetry.json.

Configuration

| Env var | Effect | | ----------------------------- | ---------------------------------------------------------------------------- | | CTXHUB_SERVER | Default ctxhub host for login / logout / bind / doctor and all API verbs. | | CTXHUB_TOKEN | Bearer token used by the full-API verb surface (PAT or copy of an OAuth access token). | | CTXHUB_TELEMETRY_ENDPOINT | Override the telemetry endpoint (only matters when telemetry is on). | | CTXHUB_NO_BROWSER | Set to 1 to keep ctxhub login from auto-launching the verification URL. | | NO_COLOR | Disable ANSI color. | | XDG_CONFIG_HOME | Override the credentials / telemetry dir (Linux / macOS). |

License

MIT