> ## 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 init > Initialize a project or global Comet environment, choose Native or Classic, and install the corresponding capabilities. `comet init` is the installation entry point. It detects platforms, installs Comet Skills, and, for project-scope initialization, sets the default workflow behind `/comet`. ## Basic usage ```bash theme={null} cd your-project comet init ``` Common options: | Option | Description | | ------------------- | ------------------------------------------------------------------------------- | | `--yes` | Run non-interactively, installing missing components and skipping existing ones | | `--scope ` | Installation scope: `project` or `global` | | `--language ` | Skill language: `en` or `zh` | | `--workflow ` | Enable `native`, `classic`, or `both` | | `--platform ` | Initialize only one supported or project-defined custom platform | | `--codegraph ` | Non-interactive CodeGraph choice: `init` or `skip` | | `--root ` | Native artifact root, such as `docs` | | `--skip-existing` | Skip existing components | | `--overwrite` | Overwrite manifest-managed files | | `--json` | Output JSON | ## Native and Classic initialization Interactive initialization offers Native, Classic, or both at project and global scope. At project scope, non-interactive initialization selects the default using these rules: 1. A valid `.comet/config.yaml` is the source of truth. 2. `--workflow native|classic|both` is an explicit choice and does not migrate existing changes. `both` keeps `/comet` on Native by default. 3. Without valid workflow configuration, Classic `.comet.yaml` state or legacy Ambient Resume evidence preserves Classic. 4. Every other project defaults to Native. Existing code, an ordinary `openspec/` directory, or `docs/superpowers/` does not change that default. Native initialization installs Comet-owned Skills and runtime, one shared workflow Rule, and one Hook Router where the platform supports Hooks. It creates: ```text theme={null} .comet/config.yaml /comet/ ``` It does not install OpenSpec, Superpowers, or CodeGraph and does not create Classic/OpenSpec changes or `docs/superpowers/`. The shared Rule and Router use `.comet/current-change.json` to send each write to one workflow Guard, never both Native and Classic. Classic initialization preserves its complete dependency set and phase governance. Comet writes and activates `.comet/config.yaml` only after required assets succeed on **every selected platform** and any existing `/comet` entry is compatible with the bundled routing contract. If an incompatible custom `/comet` entry exists, initialization preserves it and reports the run as incomplete. Re-run `comet init --workflow native --overwrite` only when you intend to replace that custom entry. ```bash theme={null} comet init --workflow native --root docs comet init --workflow classic comet init --workflow both comet init --scope global --workflow native comet init --scope global --workflow classic comet init --scope global --workflow both ``` At global scope, `--workflow` selects which capabilities are installed globally but does not write project configuration or choose a project's default workflow. Non-interactive global initialization keeps Classic as the default when `--workflow` is omitted. `--root` remains valid only for project-scope Native initialization. ## Target one platform When a project defines several platforms but this run should install or repair only one, pass `--platform`: ```bash theme={null} comet init --platform claude --workflow native comet init --platform my-team-platform --workflow classic ``` The value may be a Comet-supported platform ID or a custom platform defined by the project. With the option, initialization touches only that target. Without it, Comet continues to use automatic platform detection and the existing fallback rules. Non-interactive project initialization can also use `--codegraph init` to create or refresh the CodeGraph index, or `--codegraph skip` to skip it explicitly. Ordinary diagnostics never mutate the index. Run `comet doctor` first when you need to inspect its current state. ## Project installation registry Starting in 0.4.0-beta.4, a successful project-scope installation is recorded in a user-level project registry. The registry stores only the project location and installed platforms needed for later updates and uninstallation. It neither copies project content nor uploads usage data. After registration, interactive `comet update` and `comet uninstall` can offer the current project or every registered project. `--json` and explicit `--current-project` remain limited to the current project, and `comet uninstall --force` does too. Batch operations require an explicit `--all-projects`. Automation should pass one of these scope options instead of relying on terminal detection. ## Installation mode: copy or symlink Classic or both initialization asks for an **installation mode** after platform selection, including at global scope. Native-only initialization always uses Copy. Project-scope Native avoids `.comet/skills/`; Native change state stays under `/comet/`, while shared project configuration and selection live under `.comet/`. Symlink mode was added in 0.4.0-beta.1: * **Copy**: copy an independent set of Skill files to each platform. * **Symlink**: create links in each platform directory that point to the shared `.comet/skills/` store, saving space and making one update apply everywhere. If a platform already has its own `skills/` directory, Comet preserves it and adds links only for Comet-managed Skills. Existing local and third-party Skills are not deleted or replaced when you choose Symlink. See [Supported platforms ยท Copy or symlink](/en/platforms#copy-or-symlink) for details and guidance. ## Shared project configuration merge Native and Classic now share `.comet/config.yaml`. Initialization merges managed fields for the enabled workflows: * preserves existing values such as `native.artifact_root` and `classic.review_mode`; * adds defaults for missing managed fields; * refreshes comments to match the current version; * preserves extra custom fields; * keeps shared `default_workflow`, `workflows`, and `ambient_resume` semantics separate from `native.*` and `classic.*` settings; * fails closed when workflow configuration cannot be parsed safely instead of guessing defaults and overwriting it. The terminal reports `Project config merged (.comet/config.yaml)`. ## OpenSpec CLI installation scope OpenSpec CLI is a cross-project tool used by Classic. Even for project-scope Classic initialization, Comet installs or upgrades OpenSpec CLI globally, so this dependency does not create a project `node_modules/` directory. Native neither checks nor installs it. ## Check after initialization ```bash theme={null} comet doctor ``` If platform directories, Skill files, or scripts are missing, repair them before starting `/comet`. ## Reading the installation summary `comet init` and `comet update` report each component's installation status per platform. Skill and script copies look like this: ```text theme={null} Comet -> claude: installed (12 files) -> .claude/skills/ Comet -> claude: skipped (alreadyExists) Comet -> opencode: failed (12 files, 1 failed) -> .opencode/skills/comet ``` | Status | Meaning | | ----------- | ---------------------------------------------------------------- | | `installed` | Every file was copied successfully | | `skipped` | The component already exists and `--overwrite` was not specified | | `failed` | One or more files could not be copied | Since 0.4.0-beta.1,{' '} a partially failed installation is no longer reported as success. When any file copy fails on a platform, that platform is marked failed with a failure count. Missing comet-hook-guard.mjs breaks Classic phase checks; a missing Native entry point or runtime likewise prevents project default configuration from being written. Re-run{' '} comet init or comet update to install the missing files.