comet update

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

comet update

To update the applicable package with Comet’s candidate validation, downgrade refusal, and rollback protection, prefer:

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.

# 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 <id> 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

Resolves the asset scope — Chooses current project, all indexed projects, or explicit global/project targets before changing anything.
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.
Detects installed targets — Scans the selected project and/or home-directory platform locations for existing Comet assets.
Preserves installed language — Keeps each target’s current en or zh Skill language unless --language overrides it.
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

# Choose either an asset-only refresh or an explicit package update.
comet update --current-project
comet update --current-project --self-update
comet doctor

Flags

boolean

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.

string

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.

string

Limit asset refresh to project or global. Explicit --scope global deterministically uses current-project mode and does not imply npm self-update.

boolean

Refresh only installations resolved from the current project. Package self-update remains disabled unless --self-update is also present.

boolean

Refresh every project-scope installation in the project registry. This cannot be combined with --current-project or --scope global.

boolean

Explicitly update the applicable Comet npm package before refreshing assets. Candidate validation, downgrade refusal, and rollback safeguards apply.

boolean

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:

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

comet update --json

The current-project result includes component details. The relevant package-status excerpt for the default asset-only path is:

{
  "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.

Install and health checks

Skills, evals, and publishing

Core scripts

Basic usage

Choose the update scope

npm self-update boundary

What `update` does

When to run it

Native and Classic update boundaries

Recommended flow

Flags

Example output

JSON output

​Basic usage

​Choose the update scope

​npm self-update boundary

​What update does

​When to run it

​Native and Classic update boundaries

​Recommended flow

​Flags

​Example output

​JSON output

Basic usage

Choose the update scope

npm self-update boundary

What `update` does

When to run it

Native and Classic update boundaries

Recommended flow

Flags

Example output

JSON output