> ## 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. # comet update > Safely refresh Comet assets and update the npm package only when explicitly requested. `comet update` refreshes installed Comet Skills, Rules, Hooks, Runtime files, and managed instructions. Current-project mode refreshes assets without changing any npm installation by default. Updating the CLI package requires explicit `--self-update`. ## Basic usage ```bash theme={null} comet update ``` To update the applicable package with Comet's candidate validation, downgrade refusal, and rollback protection, prefer: ```bash theme={null} comet update --self-update ``` If you deliberately need to change only the global package, select an exact version yourself, for example `npm install -g @rpamis/comet@0.4.0-beta.8`. Direct npm installation bypasses Comet's candidate validation and downgrade protection; do not use a moving tag such as `latest` when preserving the installed version matters. ## Choose the update scope When the project registry contains project-scope installations, interactive `comet update` asks you to choose: * **All indexed projects**: update every registered project in sequence. * **Current project only**: update only the project for the current working directory. Automated calls use more conservative defaults: | Invocation | Default scope | | -------------------------------------- | -------------------------------------------------- | | Interactive call with indexed projects | Ask for current project or all registered projects | | `--json` | Current project | | Explicit `--current-project` | Current project | | Explicit `--all-projects` | All registered projects | | Explicit `--scope global` | Global asset targets in current-project mode | `--all-projects` cannot be combined with `--scope global` or `--current-project`. Explicit `--scope global` deterministically uses current-project mode and never opens the all-projects selector. It selects global asset targets without implicitly updating the global npm package. ```bash theme={null} # Refresh only the current project comet update --current-project # Refresh every registered project-scope installation comet update --all-projects # Refresh only global asset targets without changing npm comet update --scope global # Refresh one platform in the current project comet update --current-project --platform claude # Explicitly update the corresponding Comet npm package too comet update --scope global --self-update ``` Batch mode records a result for every project. Package update, target inspection, or configuration-read failures remain failed or unattempted results rather than being reported as success. Registry entries that no longer exist and can be proven to have no project installation are removed safely. Use `--platform ` when one platform is missing a Skill, Rule, or Hook, or when only a project-defined custom platform should be refreshed. The option leaves every other platform unchanged. Omitting it processes all resolved targets in the selected scope. Automation should explicitly pass `--json`, `--current-project`, or `--all-projects`. Comet does not infer scope merely because a script launched the command. Without one of these options, an indexed interactive invocation still opens the scope selector. ## npm self-update boundary Current-project mode includes explicit `--current-project`, `--json`, a default call with no indexed choice, and explicit `--scope global`. These calls do not change any npm installation by default, whether global or project-local. Only `--self-update` updates the corresponding Comet package before assets are refreshed. All-projects is a broader update mode and permits an applicable package update for each project by default; the same global package is attempted at most once. Pass `--skip-self-update` when you want to refresh only registered project assets. `--self-update` and `--skip-self-update` are mutually exclusive. Self-update compares the target installation's full semver, including prereleases, and refuses a downgrade. Before target mutation, Comet installs the exact candidate into an isolated temporary directory and validates its version, `workflow resolve`, and Native commands under bounded time and output budgets. Candidate validation failure leaves the target untouched. If the real install fails, Comet attempts to restore the exact previous version and reports the update as incomplete instead of displaying success. ## What `update` does 1. **Resolves the asset scope** — Chooses current project, all indexed projects, or explicit global/project targets before changing anything. 2. **Optionally self-updates npm** — Skips package mutation in current-project mode unless `--self-update` is present. Broader updates can disable it with `--skip-self-update`. 3. **Detects installed targets** — Scans the selected project and/or home-directory platform locations for existing Comet assets. 4. **Preserves installed language** — Keeps each target's current `en` or `zh` Skill language unless `--language` overrides it. 5. **Refreshes managed assets** — Updates Comet Skills, Rules, Hooks, Runtime files, and managed instructions while preserving unmanaged files. If no installed targets are found, `comet update` exits without claiming that assets were refreshed and recommends running `comet init` first. ## When to run it * After upgrading `@rpamis/comet`. * When `comet doctor` reports Skill or Runtime version drift. * When switching between English and Chinese Skills. * When the team updates project-level Comet configuration. ## Native and Classic update boundaries Like `comet init`, `comet update`: * A Native project refreshes Comet-owned Skills/runtime, the shared workflow Rule, Hook Router, and Ambient Resume instructions, always using Copy. It does not create `.comet/skills/` or install OpenSpec, Superpowers, CodeGraph, or Classic-only Skills. An old symlink install is safely detached and materialized as local copies without writing through to `.comet/skills/`; if a shared linked directory contains unmanaged Skills, Comet preserves it and refuses replacement. * Classic and global targets retain the existing Copy/Symlink choice and dependency set. Symlink mode rebuilds links under `.comet/skills/`. * `.comet/config.yaml` is merged field by field as shared project configuration, preserving the other workflow and user fields. A Native update does not delete existing Classic files, and changing the default entry point is not a workflow migration. * `ambient_resume` controls the same read-only Ambient Resume instructions for Native and Classic. When set to `false`, update removes the managed resume block while preserving other user rules. An existing platform `skills/` directory is preserved. Symlink mode refreshes only Comet-created links and leaves local or third-party Skills untouched. ## Recommended flow ```bash theme={null} # Choose either an asset-only refresh or an explicit package update. comet update --current-project comet update --current-project --self-update comet doctor ``` ## Flags Suppress progress output and print one structured JSON result. JSON mode always uses current-project scope unless `--all-projects` is explicit, and it does not update npm without `--self-update`. Override the auto-detected Skill language for every selected target. Accepted values are `en` and `zh`. Without this flag, each target keeps its installed language. Limit asset refresh to `project` or `global`. Explicit `--scope global` deterministically uses current-project mode and does not imply npm self-update. Refresh only installations resolved from the current project. Package self-update remains disabled unless `--self-update` is also present. Refresh every project-scope installation in the project registry. This cannot be combined with `--current-project` or `--scope global`. Explicitly update the applicable Comet npm package before refreshing assets. Candidate validation, downgrade refusal, and rollback safeguards apply. Explicitly disable npm package self-update, including in all-projects mode. It cannot be combined with `--self-update`. ## Example output An asset-only current-project refresh reports the npm step as skipped and still refreshes managed targets: ```text theme={null} Comet Update Updating Comet assets on 1 installed target: Claude Code (project, en): assets refreshed Summary: npm: skipped assets: complete scope: project Update complete. ``` Pass `--self-update` to add the isolated candidate validation and package installation before this asset refresh. ## JSON output ```bash theme={null} comet update --json ``` The current-project result includes component details. The relevant package-status excerpt for the default asset-only path is: ```json theme={null} { "status": "complete", "failures": [], "npm": { "scope": "skipped", "status": "skipped", "command": null, "exitCode": null, "reason": "self-update disabled for current-project updates; pass --self-update to opt in" } } ``` The `npm.status` field is one of: | Value | Meaning | | --------- | ------------------------------------------------------------------------------------------------ | | `updated` | The exact validated candidate was installed successfully. | | `failed` | Candidate inspection, validation, installation, or rollback failed; the run is incomplete. | | `skipped` | Package mutation was disabled or no newer allowed version needed installation; inspect `reason`. | Use `comet update --current-project` for a safe asset-only refresh. Add `--self-update` only when you also intend to change the installed CLI package. `comet update` does not manage OpenSpec, Superpowers, or other third-party Skills. Native targets additionally skip CodeGraph and Classic-only Skills; Classic targets retain their existing behavior. Unmanaged local or third-party Skills are preserved.