CovenDocs

Install Debugging

Debugging guide for Coven CLI installation problems across npm, native platform packages, and Cargo/source builds.

8 min read

This page has platform-specific steps.

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 doctor

doctor 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 doctor

Install Decision Flow

Rendering diagram…

Fast Triage

SymptomLikely causeFix
coven: command not foundInstall dir not on PATH, or global install failedConfirm install method, then add its bin dir to PATH.
coven runs an old version after an upgradeA second install is first on PATH, or npm install -g wrote to a different npm prefix than the one your shell resolvesRun 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 npxStale npx cacheCompare coven --version with npm view @opencoven/cli version; clear the cache and rerun.
npm warns about a missing optional dependencyThe native platform package did not resolve for your OS/CPUReinstall @opencoven/cli from the environment where you run it.
Unsupported platform on installOS/CPU is not covered by a published native packageBuild from source, or use a supported platform / WSL2.
Source build fails to compileToolchain or dependency mismatchUpdate 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 --version

Windows

Get-Command -All coven
coven --version

Multiple 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-cli

The 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 doctor

If 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@latest

How the copies get there

CauseWhat happensPlatforms
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 managerTwo 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 managerSame 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 installerIt used to write a coven alias into ~/.coven-code/bin and add that directory to PATH.macOS, Linux
Native Windows and WSL2These 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 -g

On 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@latest

Doctor 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 doctor

If 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 --version

Then upgrade the install Doctor named, using its origin:

  • npm, prefix <dir>: npm install -g --prefix <dir> @opencoven/cli@latest
  • cargo install: cargo install --path crates/coven-cli --force from an up-to-date checkout
  • source 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 doctor

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

PlatformOS/CPUNative 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 version

On 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 -- doctor

If the build fails to compile, update the Rust toolchain and retry from a clean state:

rustup update stable
cargo clean
cargo build --workspace

To install the built binary onto your Cargo bin path:

cargo install --path crates/coven-cli
coven doctor

Roll 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 doctor

If 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 -- doctor

Never 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 --version and the Install/Installs block from coven doctor, plus which -a coven on Unix-like shells or Get-Command -All coven in PowerShell.
  • Your OS and CPU architecture.
  • For npm installs, the output of npm view @opencoven/cli version, the matching platform-package npm view command above, and any missing-optional-dependency warning.
  • For source builds, the failing cargo build output.

Do not paste secrets or private paths into a report. Once coven runs, continue with Doctor.

Was this page helpful?No

Last updated on

On this page