Skip to main content
This page focuses on four high-frequency topics: installation and initialization, status and diagnostics, upgrade and uninstall, and Skill evaluation/publishing commands.

​
Installation and initialization

No. When an existing component is detected, comet init lets you choose to overwrite or skip it. Hooks merge non-destructively, keeping the hooks you already have. In --yes mode, existing components are skipped by default. To force a refresh, use --overwrite.
Some files failed to copy on this platform (for example, a Skill or script file was not installed). Since 0.4.0-beta.1, such failures are truthfully marked failed with a failure count. Missing critical files such as comet-hook-guard.mjs would silently break the phase guard, so they must be repaired first. Re-run comet init or comet update to restore the missing files. See Reading the installation summary.
comet-hook-guard.mjs itself crashed (bundle damage, import failure, or an unexpected throw). It fails closed: it prints a [COMET-HOOK] crash: ... diagnostic and blocks the write with exit code 2. This means the phase guard is unavailable, most often because a required script is missing.Use a fixed recovery sequence: run comet doctor to identify missing assets, run comet init or comet update to restore them, then retry the original action.
Since 0.4.0-beta.1, all scripts run through Node.js, and Windows no longer requires Bash, Git Bash, or WSL. macOS, Linux, and Windows use the same set of commands.
Project level suits team projects (configuration is written into the repository for collaboration), and global suits a personal default environment (written to the user directory and shared across projects). When in doubt, start with project level. For more details, see comet init.
The current release supports 37 AI coding platforms, including Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, Oh My Pi, and DeepSeek Harness. comet init will automatically detect the existing platform directories in the project and pre-select them. The Skill, Rule, and Hook capabilities supported by different platforms vary. For details, see Supported platforms.

​
Status and Diagnosis

Starting from 0.4.0-beta.4, the project instructions generated by install or update have the Agent run a read-only recovery probe first. Recovery is only recommended when there is exactly one clearly relevant active change that is not at a decision point. With multiple changes, uncommitted changes, or an unrelated request, the Agent asks first or answers normally; it never forces entry into a workflow. For details, see the resume probe command.
comet status answers “where am I in the flow and what should I run next?”. comet doctor answers “why is this failing and what is broken?”.In practice, start with status and run doctor only when status looks wrong or recovery fails.
warn is generally advisory (for example, an optional dependency is missing). fail is blocking (for example, missing Skills or corrupted state).Clear all fail items first, then handle warn based on impact. For details, see comet doctor.
CodeGraph CLI, project index, MCP registration and Agent effective capability are four independent states. If the CLI is installed and the index is up to date, it only indicates that the project data is ready. The corresponding Agent also needs to register a valid MCP pointing to the CodeGraph service before it will be displayed as “effective”.Run comet doctor --json and check codegraph.cliStatus, indexStatus, mcpStatus, agents and effectiveForAgent. Fix the missing links according to the actual diagnosis in the output. Do not skip the MCP check just because the index is normal.
First, run comet doctor to see if there are any malformed .comet.yaml files or missing evidence. After the repair, run status again. For troubleshooting abnormal state, see State recovery.
Starting from 0.4.2, read-only Classic and Native queries reuse an on-demand, project-scoped daemon instead of starting a fresh Node process for each query. It is project-scoped, exits after an idle period, and Comet automatically falls back to direct execution when it is unavailable, so results stay correct.Manage it with:

​
Upgrade and Uninstall

Interactive updates can update the applicable npm packages and refresh the Skill, Rule, Hook, Runtime and managed configuration in the registered projects. After completion, run comet doctor to confirm the installation is healthy:
By default, --current-project, --scope global or --json only refresh assets and do not update npm packages. When using these limited modes and needing to upgrade the CLI simultaneously, explicitly add --self-update:
The Native Portable State, Supervisor, Personal Memory, Project Knowledge and platform adaptation of RC1 all rely on the Runtime and managed assets released with the version. Upgrading only the npm package without running comet update will cause the project to continue using the old assets.
No. comet uninstall only removes the skills, rules and hooks managed by Comet and keeps your OpenSpec changes, design documents, implementation plans and project code. For more details, see comet uninstall.
Use comet init for first-time setup or when adding a new platform to a project. Use comet update after version upgrades to refresh what is already installed.Both follow a non-destructive policy for existing user configuration unless you explicitly choose overwrite.

​
Skills, evaluation and publishing commands

When creating reusable Skills, prefer /comet-any, which invokes the CLI backend internally. comet skill is a low-level tool, suitable for local debugging, advanced Skill execution, and package management. See comet skill.
comet eval assesses the product capabilities of a Skill and produces pre-release evidence. comet skill check verifies whether a certain Skill run is missing an artifact or status, without generating release evidence. Publish readiness only needs comet eval. See comet eval.
Ordinary users use comet publish (the user publishing entry). comet bundle is an advanced backend used directly only for backend-status checks, auditing, or automated integration. See comet publish.

​
CI/CD

Skip all prompts with --yes --json:
Yes. The JSON structure of status and doctor is part of the CLI contract. CI gates should exit non-zero only on doctor fail results. For details, see CI/CD integration.
Last modified on September 21, 2026