> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and update

> The full path from installing the Comet CLI to initializing a project, refreshing assets, health checks, and uninstalling.

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

```bash theme={null}
npm install -g @rpamis/comet
```

Confirm the command is available:

```bash theme={null}
comet -v
```

## 2. Initialize a project

Run the install entry point from your project root:

```bash theme={null}
cd your-project
comet init
```

`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:

```bash theme={null}
comet init --workflow native --root docs
comet init --workflow classic
comet init --workflow both
comet init --scope global --workflow native
```

For the full set of options and the Native/Classic initialization boundaries, see [comet init](/en/cli/init).

### Install scope: project or global

| Scope   | Suited for                                                      | Characteristics                                                             |
| ------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| project | Team projects, repo conventions, configs that must be committed | Config is written into the current project, easy to collaborate on          |
| global  | Personal default environment, shared across projects            | Config is written to the user directory, convenient when switching projects |

When unsure, start with project scope — it's the easiest way to keep the whole team on the same Comet behavior.

### Install mode: copy or symlink

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](/en/platforms#install-mode-copy-vs-symlink).

<Warning>
  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 <strong>Copy</strong> mode.
</Warning>

## 3. Update Comet

Update Comet as follows — it pulls the new npm package and refreshes the installed Skill, Rule, Hook, Runtime, and config:

```bash theme={null}
comet update
```

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

<Note>
  When you limit the scope to a single project with <code>--current-project</code> or <code>--json</code>, it refreshes assets only and does not update the npm package by default. To also update the package in that mode, add <code>--self-update</code>.
</Note>

For update scope and Native/Classic update differences, see [comet update](/en/cli/update).

## 4. Health check

Whenever something looks off, run `comet doctor` for a full installation health check:

```bash theme={null}
comet doctor
```

`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](/en/cli/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.

```bash theme={null}
comet uninstall
```

Batch uninstall requires an explicit `--all-projects`. See [comet uninstall](/en/cli/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

* Full first-run walkthrough: [Quickstart](/en/quickstart).
* All supported platforms: [Supported platforms](/en/platforms).
* More questions about installation and initialization: [CLI FAQ](/en/cli/faq).