Install Debugging

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

Fast Triage

Identify The Binary You Are Actually Running

Unix-like shells

which -a coven
coven --version

PowerShell

Get-Command -All coven
coven --version

Multiple entries mean more than one install is on your search path. Remove the stale copy or move the intended install earlier on PATH before debugging anything else.

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.

Unix-like shells

which -a coven
echo "$PATH" | tr ':' '\n'

PowerShell

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

npx caches packages, so a one-off invocation can run an older CLI than you expect. Compare the running binary with the published wrapper version:

npm view @opencoven/cli version
coven --version

Then check the actual command resolution in the shell where you launched it:

which -a coven

Get-Command -All coven

Reinstall the latest global build, or clear the npx cache and rerun:

npm install -g @opencoven/cli@latest
coven doctor

If more than one coven appears in which -a coven or Get-Command -All coven, an earlier install is shadowing the new one on PATH. Remove the stale copy or reorder PATH so the intended install wins.

Missing Or Mismatched Native Platform Package

The npm wrapper @opencoven/cli resolves a matching native package as an optional dependency. The published target matrix currently covers macOS Apple Silicon (darwin-arm64), macOS Intel (darwin-x64, package @opencoven/cli-macos-x64), Linux x64 (linux-x64), and Windows x64 (win32-x64). If npm cannot resolve the package for your OS/CPU pair, coven will not run even though the wrapper installed.

Check that the wrapper and the native package you expect are both published:

npm view @opencoven/cli 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, 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.