Skip to main content
This page ties Comet’s installation, initialization, update, health check, and uninstall into one complete path. Each step links to the more detailed command page for when you need to go deeper.

​
Prerequisites

  • Node.js 22 or higher
  • npm or npx
  • Git
  • A supported AI coding platform, such as Claude Code, Codex, Cursor, Gemini CLI, OpenCode, or ZCode

​
1. Install the CLI

Confirm the command is available:

​
2. Initialize a project

Run the install entry point from your project root:
comet init detects platforms, installs the Comet Skill, and decides the default workflow for /comet during project-level initialization. New projects default to Native; projects with an existing explicit Classic state stay Classic. You can also choose explicitly:
For the full set of options and the Native/Classic initialization boundaries, see comet init.

​
Install scope: project or global

When unsure, start with project scope — it’s the easiest way to keep the whole team on the same Comet behavior. Classic or both initialization asks for the install mode after you pick platforms:
  • Copy (default): copies an independent set of Skill files for each platform, suited for cross-device sync (committed to the repo).
  • Symlink: creates symlinks in each platform’s skills/ directory pointing to .comet/skills/, so multiple platforms share one central store and a single update applies everywhere.
Installing only Native always uses Copy. For the detailed differences between the two modes, see Supported platforms · Install mode.
Symlinks depend on filesystem support. Some Windows configurations or sync tools (such as certain cloud drives) may not handle symlinks correctly. If you run into issues, fall back to Copy mode.

​
3. Update Comet

Update Comet as follows — it pulls the new npm package and refreshes the installed Skill, Rule, Hook, Runtime, and config:
When you choose to update all indexed projects in an interactive comet update, the corresponding npm packages are updated as well (the global package is attempted at most once).
When you limit the scope to a single project with —current-project or —json, it refreshes assets only and does not update the npm package by default. To also update the package in that mode, add —self-update.
For update scope and Native/Classic update differences, see comet update.

​
4. Health check

Whenever something looks off, run comet doctor for a full installation health check:
doctor checks Skill, scripts, working directory, and change state:
  • fail is a blocking issue (such as a missing Skill or corrupted state) and must be addressed first.
  • warn is usually non-blocking (such as the openspec CLI not installed when the project doesn’t depend on it).
See comet doctor.

​
5. Uninstall

comet uninstall removes only the Skill, rules, and hooks managed by Comet, and keeps your OpenSpec changes, design docs, implementation plans, and project code.
Batch uninstall requires an explicit --all-projects. See comet uninstall.

​
When to reinstall or update

  • After upgrading @rpamis/comet.
  • When comet doctor reports a Skill or script version mismatch.
  • When switching between Chinese and English Skills.
  • After your team updates the project-level Comet config.
  • When the install summary shows failed for a platform, or a hook reports [COMET-HOOK] crash on file writes — usually an incomplete install. Re-run comet init/comet update to fill in the missing files.

​
Next steps

Last modified on August 2, 2026