@contextq/cli

@contextq/cli

One-command installer for ContextQ. It wires the ContextQ MCP server and the contextq SessionStart boot hook into a project, and gitignores the read-only render of its cloud task board — or prints a manual connect guide when the surface is Claude Desktop or Cowork, which have no project files to write into.

Install

npx @contextq/cli init

Or install it globally and call the contextq binary directly:

npm install -g @contextq/cli
contextq init

contextq init

Detects which agent surfaces the current directory and machine are set up for (Claude Code, Codex, Gemini CLI, Cursor, Copilot CLI — often several at once) and writes the wiring each one needs.

Option	Meaning
--key <sk_live_...>	API key. Falls back to CONTEXT_API_KEY / CTQ_API_KEY in the environment, then to an interactive prompt.
--url <url>	ContextQ API URL. Defaults to https://app.contextq.dev; point it at your own instance when self-hosting.
--workspace <slug>	Workspace the boot hook reads from. Defaults to the repo basename, sanitized. Lowercase letters, digits, - and _; must start with a letter or digit; 64 chars max. Case is folded to lowercase, since workspace slugs always are.
--agent <slug>	Agent identity the session boots and checkpoints under. Same defaulting and same character rules as --workspace.
--embed-key	Write the literal API key into .mcp.json instead of the ${CONTEXT_API_KEY} placeholder. Opt-in on purpose: it trades a secret sitting on disk for not having to export the variable.
--surface <s>	Force detection to exactly one of claude-code, codex, gemini, cursor or copilot, skipping autodetection.
--no-plugin	Wire Claude Code through .mcp.json even when Claude Code 2.1.281+ is installed.
-h, --help	Show usage.

The API key is a ContextQ key in the form sk_live_<40 hex>: a new account's first key is shown once on the dashboard's Connect an Agent page, and more are created at API Keys. Every plan can create keys up to its active-key cap: Free 3, Pro 20, Team and Enterprise unlimited (keys that back MCP OAuth connectors do not count). Without --embed-key, the generated config references ${CONTEXT_API_KEY} and the key never lands in a file.

Claude Code: plugin first, .mcp.json as the fallback

When a claude binary of version 2.1.281 or newer is on PATH, init installs the ContextQ Claude Code plugin at project scope instead of writing .mcp.json: it declares the marketplace and enables contextq@contextq-plugins in the repo's .claude/settings.json, and hands the key to Claude Code through claude plugin install --config apiKey=..., so it lands in Claude Code's own store rather than in a file or your shell profile. The plugin carries the MCP server and the SessionStart / PreCompact / SessionEnd hooks, so init writes no hook of its own on this path. Finish by running /contextq:init in a Claude Code session to bind the repo to a workspace and project; until then the hooks stay silent and say so.

init falls back to .mcp.json when the binary is missing or older, when the install reports a failure, or when .mcp.json already wires contextq (installing the plugin on top would register the same MCP server twice). Running init in a second repo with a different key replaces the key the first repo's plugin uses, because the plugin's apiKey is stored once per machine, not per repo.

init checks the key against GET /api/workspaces before it writes anything. A key the server refuses with 401 or 403 is never saved and nothing is wired: from a terminal init asks for a replacement (also when the refused key is the one already stored), otherwise it exits 1 and names init --key. A server that cannot be reached is not treated as a bad key: the key is saved with a could not verify warning, and the host configs that would carry it are skipped.

Gemini CLI, Cursor and Copilot CLI: remote MCP in the host's own config

A host is detected when its user config directory exists: ~/.gemini/, ~/.cursor/ (Cursor and cursor-agent share it), or ~/.copilot/ ($COPILOT_HOME when set). init adds a contextq entry pointing at <url>/mcp to ~/.gemini/settings.json (httpUrl), ~/.cursor/mcp.json (url) or ~/.copilot/mcp-config.json (type: http), leaves every other key in the file alone, and sets the file to mode 600. The key goes into the Authorization header as a literal, because Gemini CLI does not expand variables in headers and the other two would need the variable in the GUI app's environment. An existing contextq entry is left as it is.

It refuses, and changes nothing, when the file is not valid JSON, or when it sits in a git work tree without being gitignored (some people track ~/.gemini/ in git), since the key would end up in a commit. It also skips all three when the key fails the connection check. Gemini CLI loads user-level MCP servers only in a trusted folder.

The SessionStart boot hook (--no-plugin and Codex)

Without the plugin, init writes a SessionStart hook to .claude/settings.local.json (Claude Code) and .codex/hooks.json (Codex, gitignored by init). The hook runs npx -y --prefer-offline @contextq/cli hook boot --format <host>, which reads the key from the credentials file init wrote (or CONTEXT_API_KEY), resolves the repo from the session's working directory, and asks POST /api/agent/hooks/session-start for the boot pack: the same endpoint and output the plugin hook uses. A refused key or an unreachable server prints one line saying so instead of nothing. init refuses, and changes nothing, when the hook file is not valid JSON or is tracked by git. Codex runs a project hook only after you trust it: start codex in the repo and approve it at the hook-trust prompt.

Gemini CLI, Cursor and Copilot CLI: user-level boot hooks

Next to the MCP entry, init adds a session-start hook to the host's user-level config: hooks.SessionStart in ~/.gemini/settings.json, hooks.sessionStart in ~/.cursor/hooks.json, and its own ~/.copilot/hooks/contextq.json ($COPILOT_HOME/hooks/ when set). The hook runs npx -y --prefer-offline @contextq/cli hook boot --format <host> --require-config: it takes the repo from the session's working directory and stays silent in any repo without a .contextq/config.json, so one user-level hook serves every bound repo and nothing else. init writes that .contextq/config.json for the current repo when it is missing (commit it). The same refusals apply as for the MCP entry (invalid JSON, a git-tracked config). Cursor runs sessionStart without waiting for it, so the first turn may start before the pack arrives.

Codex: remote MCP in the project's .codex/config.toml

init --surface codex (or a detected Codex) adds [mcp_servers.contextq] with url = "<url>/mcp" and an [mcp_servers.contextq.http_headers] table carrying Authorization = "Bearer <key>" to the repo's .codex/config.toml, appends .codex/config.toml to .gitignore, and sets the file to mode 600. Existing content is kept byte for byte and an existing contextq entry is left alone. It refuses, and changes nothing, when the file is not valid TOML, when mcp_servers is an inline table the new block cannot extend, or when the file is tracked by git. Codex reads a project config only in a trusted project: run codex once in the repo and accept the trust prompt, then codex mcp list shows contextq. If no surface ends up with an MCP connection, init says so and exits 1 instead of printing Done.

contextq skills sync <dir>

Pulls this tenant's distilled procedures — the parametrized skills ContextQ mines from repeated, independently verified agent task patterns — into <dir> as standard Agent Skills folders, one SKILL.md per procedure.

contextq skills sync .claude/skills

Safe to re-run. An existing folder is matched by its own metadata.cluster_key and rewritten in place rather than duplicated. A folder whose source context no longer resolves is reported as an orphan and left on disk untouched, so nothing you wrote by hand is ever deleted.

It accepts --workspace, --key and --url with the same meanings as init.

Requirements

Node 18 or newer, and a reachable ContextQ instance — the hosted one at app.contextq.dev or your own.

License

MIT. Source lives in the contextq repository under cli/.

Releasing

Whoever publishes runs bash scripts/check-npm-pack.sh cli from the repo root and publishes the tarball= file it prints, never a bare npm publish in this directory: the check refuses sourcemaps, TypeScript source and tests in the real tarball (T922).