@contextq/cli

@contextq/cli

One-command installer for ContextQ. It wires the ContextQ MCP server, the contextq SessionStart boot hook, and the task manifest into a project — 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 is set up for (Claude Code, Codex, or both — a repo is often both 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 or codex, skipping autodetection.
-h, --help	Show usage.

The API key is a ContextQ key in the form sk_live_<40 hex>, issued from your tenant's dashboard. Without --embed-key, the generated config references ${CONTEXT_API_KEY} and the key never lands in a file.

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/.