Install Debugging
Debugging guide for Coven CLI installation problems across npm, native platform packages, and Cargo/source builds.
8 min read
Use this page when installing the Coven CLI did not produce a working coven command. For runtime failures after a successful install (daemon, harness, or session problems), see Troubleshooting and Harness Troubleshooting.
Start With Doctor
If coven runs at all, run it first:
coven doctordoctor reports store, project, daemon, socket, and harness readiness. If coven doctor fails because the command is not found, work through the sections below.
If coven is not on PATH yet, you can still exercise the published package without a global install:
npx @opencoven/cli doctor
pnpm dlx @opencoven/cli doctorInstall Decision Flow
Fast Triage
| Symptom | Likely cause | Fix |
|---|---|---|
coven: command not found | Install dir not on PATH, or global install failed | Confirm install method, then add its bin dir to PATH. |
coven runs an old version after an upgrade | A second install is first on PATH, or npm install -g wrote to a different npm prefix than the one your shell resolves | Run coven doctor; the richer Installs: block format (OpenCoven/coven#1124) names every copy, its origin, and the removal command, while current releases print the older path-only list. See More Than One coven On PATH. |
coven runs an old version via npx | Stale npx cache | Compare coven --version with npm view @opencoven/cli version; clear the cache and rerun. |
| npm warns about a missing optional dependency | The native platform package did not resolve for your OS/CPU | Reinstall @opencoven/cli from the environment where you run it. |
Unsupported platform on install | OS/CPU is not covered by a published native package | Build from source, or use a supported platform / WSL2. |
| Source build fails to compile | Toolchain or dependency mismatch | Update Rust stable and retry a clean cargo build. |
Identify The Binary You Are Actually Running
In the CLI release that includes OpenCoven/coven#1124, coven doctor prints this first as an Install: line (one copy, with its origin) or an Installs: block (several copies). Until then, Doctor prints the older path-only list. If coven does not run at all, list the candidates yourself:
macOS · Linux
which -a coven
coven --versionWindows
Get-Command -All coven
coven --versionMultiple entries mean more than one install is on your search path; continue with the next section before debugging anything else.
More Than One coven On PATH
This is the most common cause of "I upgraded and nothing changed". The first coven on PATH answers every command, so an upgrade applied to any other copy is invisible. Until the CLI release that includes OpenCoven/coven#1124, Doctor still prints the older path-only list; treat the block below as the forthcoming format. Doctor lists each copy in resolution order, says how it was installed, marks the one that is the running process, and prints the command that removes each shadowed copy:
Installs:
[OK] ~/.local/bin/coven (active, this process) — npm, prefix ~/.local
[!!] ~/.nvm/versions/node/v24.18.1/bin/coven (shadowed) — npm, prefix ~/.nvm/versions/node/v24.18.1
remove: npm uninstall -g --prefix ~/.nvm/versions/node/v24.18.1 @opencoven/cli
[!!] ~/.cargo/bin/coven (shadowed) — cargo install
remove: cargo uninstall coven-cliThe first entry wins. Keep one install per machine: remove the shadowed copies with the commands above, then re-check with coven --version.
Run the remove: commands, then confirm a single copy remains and the daemon is running that same binary:
coven doctor
coven daemon restart
coven doctorIf Doctor reports that npm install -g writes to a shadowed copy or to a prefix with no coven on PATH, upgrade the prefix that owns the active copy (for current releases, use the first path from which -a coven / Get-Command -All coven to identify it):
npm install -g --prefix <active-prefix> @opencoven/cli@latestHow the copies get there
| Cause | What happens | Platforms |
|---|---|---|
| Node version managers (nvm, fnm, volta, nvm-windows) | Every Node version has its own npm prefix. npm install -g writes to the active version's prefix; switching versions later leaves the old copy behind, and a fresh install in the new version makes a second one. With nvm, a copy in an inactive version drops off PATH entirely, so coven "disappears" after nvm use. | macOS, Linux, WSL2, Windows |
A user-set npm prefix (npm config set prefix, NPM_CONFIG_PREFIX, a ~/.local prefix) alongside a version manager | Two prefixes, both with bin on PATH. Whichever is earlier on PATH wins; npm install -g writes to the prefix reported by npm prefix -g, which may be the user-set prefix or the active Node's prefix. | macOS, Linux, WSL2 |
| Homebrew or system Node plus a version manager | Same as above: /opt/homebrew/bin or /usr/local/bin holds one copy, the version manager another. | macOS, Linux |
cargo install --path crates/coven-cli from a checkout, plus the npm wrapper | ~/.cargo/bin/coven (or %USERPROFILE%\.cargo\bin\coven.exe) and the npm shim both answer to coven. Contributors hit this. | all |
| An older standalone coven-code installer | It used to write a coven alias into ~/.coven-code/bin and add that directory to PATH. | macOS, Linux |
| Native Windows and WSL2 | These are separate environments with separate PATHs; a copy in one never shadows the other. Debug each side in its own shell. | Windows |
Which prefix does npm install -g use right now?
The command is the same in every shell:
npm prefix -gOn macOS, Linux, and WSL2 the executable is <prefix>/bin/coven; on Windows it is <prefix>\coven.cmd next to <prefix>\node_modules, with %APPDATA%\npm as the default prefix for a system Node and a per-version directory under nvm-windows or volta. If that prefix is not the one holding the active copy, either remove the active copy and reinstall into this prefix, or upgrade the active copy explicitly:
npm install -g --prefix <prefix-of-the-active-copy> @opencoven/cli@latestDoctor prints exactly this command when it applies.
coven Command Not Found
The fix depends on how you installed.
npm global install
Confirm npm's global bin directory and that it is on PATH:
npm root -g
npm prefix -g
echo "$PATH" | tr ':' '\n' | grep -Fx "$(npm prefix -g)/bin"On macOS and Linux the global bin directory is <prefix>/bin, which is exactly what the last command checks for; on Windows the prefix itself is the bin directory, so look for the npm prefix -g value in Path instead. (npm bin -g printed the directory directly, but the command was removed in npm 9.)
If the global bin directory is missing from PATH, add it in your shell profile, open a new terminal, and retry:
coven doctorIf the global bin directory was missing from PATH, refresh the shell after you update it. The current process keeps the old PATH until you open a new terminal session or reload your profile. On PowerShell, open a new window before rerunning Get-Command -All coven.
If the global install itself failed (for example, permission errors writing to the global prefix), prefer a user-writable npm prefix or a version manager over sudo npm install -g.
Native binary
If you downloaded a native binary directly, make sure its directory is on PATH.
macOS · Linux
which -a coven
echo "$PATH" | tr ':' '\n'Windows
Get-Command -All coven
$env:Path -split ';'Source build
If you built with Cargo, make sure Cargo's bin directory is on PATH:
echo "$PATH" | tr ':' '\n' | grep "$HOME/.cargo/bin"Wrong Or Stale Version
If coven doctor shows a single install and coven --version is still older than the published wrapper, compare the two:
npm view @opencoven/cli version
coven --versionThen upgrade the install Doctor named, using its origin:
npm, prefix <dir>:npm install -g --prefix <dir> @opencoven/cli@latestcargo install:cargo install --path crates/coven-cli --forcefrom an up-to-date checkoutsource build: rebuild the checkout it points into
npx caches packages, so a one-off invocation can run an older CLI than the global install. Clear the cache or pin the version:
npx @opencoven/cli@latest doctorIf coven doctor shows more than one install, go back to More Than One coven On PATH first; upgrading a shadowed copy changes nothing.
Missing Or Mismatched Native Platform Package
The npm wrapper @opencoven/cli resolves a matching native package as an optional dependency. If npm cannot resolve the package for your OS/CPU pair, coven will not run even though the wrapper installed. The published target matrix, from Coven's release metadata:
| Platform | OS/CPU | Native package |
|---|---|---|
| macOS (Apple Silicon) | darwin-arm64 | @opencoven/cli-macos |
| macOS (Intel) | darwin-x64 | @opencoven/cli-macos-x64 |
| Linux (x64) | linux-x64 | @opencoven/cli-linux-x64 |
| Windows (x64) | win32-x64 | @opencoven/cli-windows |
Reinstall from the environment where you run Coven
Installing on one platform and copying node_modules to another skips the native package for the target. Reinstall @opencoven/cli from the same OS/CPU where you plan to run coven.
Check that the wrapper and the native package you expect are both published:
npm view @opencoven/cli version
npm view @opencoven/cli-macos version
npm view @opencoven/cli-macos-x64 version
npm view @opencoven/cli-linux-x64 version
npm view @opencoven/cli-windows versionOn an Intel Mac, confirm node -p "process.platform + '-' + process.arch" prints darwin-x64. If it does not, reinstall Node for a native Intel shell first, then reinstall @opencoven/cli so npm can resolve @opencoven/cli-macos-x64.
The published wrapper currently targets darwin-arm64, darwin-x64, linux-x64, and win32-x64. Alpine/musl is not covered by the published wrapper today. On an unsupported platform, build from source or use a compatible WSL2 Linux distro — see Platforms.
Windows And WSL2 Are Separate Installs
Native Windows PowerShell and WSL2 are separate environments. Run npm install, coven doctor, and Get-Command -All coven in PowerShell when you plan to use native Windows. Run npm install, coven doctor, and which -a coven inside WSL2 when you plan to use the Linux install there.
A Windows install does not satisfy WSL2, and a WSL2 install does not satisfy PowerShell. Keep the binaries, package-manager cache, and COVEN_HOME separate across that boundary.
Wrapper / native package mismatch
If @opencoven/cli installed but the resolved binary is missing, stale, or built for the wrong platform, remove the stale copy and reinstall @opencoven/cli in the target environment so the matching optional dependency is selected again. Do not copy node_modules, extracted archives, or coven binaries across macOS, Linux, Windows, or WSL2 to paper over the mismatch.
Source Build Failures
Build from source when you are contributing, testing unreleased behavior, or running on an unsupported npm platform:
git clone https://github.com/OpenCoven/coven.git
cd coven
cargo build --workspace
cargo run -p coven-cli -- doctorIf the build fails to compile, update the Rust toolchain and retry from a clean state:
rustup update stable
cargo clean
cargo build --workspaceTo install the built binary onto your Cargo bin path:
cargo install --path crates/coven-cli
coven doctorRoll Back To A Verified Release
If the newest package is broken for your environment, roll back by reinstalling a published version you have already verified for that same OS/CPU:
npm view @opencoven/cli versions --json
npm install -g @opencoven/cli@<verified-version>If the failing install was from source, choose the rollback that matches how you run Coven from that checkout.
If you installed the CLI from a source checkout onto your Cargo bin path, check out a verified prior tag there and replace the installed binary:
git checkout <verified-tag>
cargo install --path crates/coven-cli --force
coven doctorIf you run Coven directly from an active-development checkout, check out the verified prior tag in that repository and rebuild there:
git checkout <verified-tag>
cargo build --workspace
cargo run -p coven-cli -- doctorNever copy macOS, Linux, Windows, or WSL-built binaries between platforms to "roll back" faster. Reinstall or rebuild inside the target environment so the correct native package and ABI are selected.
Evidence To Collect
When an install problem needs a support report, include:
- The install method (
npx, global npm, native binary, or source build). - The output of
coven --versionand theInstall/Installsblock fromcoven doctor, pluswhich -a covenon Unix-like shells orGet-Command -All covenin PowerShell. - Your OS and CPU architecture.
- For npm installs, the output of
npm view @opencoven/cli version, the matching platform-packagenpm viewcommand above, and any missing-optional-dependency warning. - For source builds, the failing
cargo buildoutput.
Do not paste secrets or private paths into a report. Once coven runs, continue with Doctor.
Last updated on