CLI Reference

envy is one binary with one subcommand per workflow. Most days you need one of them, sync. The rest exist for spec authors, depot publishers, and CI.

Conventions

These hold for every command, so the per-command pages do not repeat them.

Examples call envy by bare name. That assumes the shell hook put the project's bin directory on PATH. Without the hook, run the committed bootstrap script directly, as ./bin/envy or bin\envy.bat. The two are the same program, since the bare name resolves to that same script.

Global flags go before the subcommand. Write envy --verbose sync. The reverse, envy sync --verbose, is a parse error. Per-command flags go after the subcommand.

stdout is for machines, stderr is for you. Progress, summaries, warnings, and errors go to stderr. The commands whose output is the answer write it to stdout: product, package, hash, export, merge-depot, git-resolve, import for a single archive, cache, and version --licenses. Piping never captures decoration.

Manifest-aware commands find the manifest by discovery, walking up to the project root from the directory the anchor names. Anchor precedence is --manifest, which names a file outright and skips the walk, then the global --project <dir>, then the current directory. --subproject means "the manifest nearest to where I stand", so it anchors on the current directory even under --project, and stops the walk at the first manifest it finds.

The bootstrap and wrapper scripts in a project's bin directory inject --project <their own directory> ahead of your arguments. That is what lets ../other-project/bin/uv run ./script.py operate on the other project rather than on whatever project your shell is standing in. The option takes the last value, so a --project you type still wins.

Manifest-aware commands re-exec into the pinned envy. If the manifest's @envy version names a version other than the running binary, envy downloads that version and hands off to it before doing any work. You get the version the project pins, not the one you typed. sync, install, deploy, vendor, product, package, run, export, and import do this. use and cache do not. They read the manifest header as text, so they keep working when the pinned version cannot run. Set ENVY_NO_REEXEC to suppress the hand-off while debugging. See Re-exec for where the release comes from and when the hand-off is refused.

Exit status is 0 on success and non-zero on failure. The exception is envy run, which returns its child's exit code.

Every command works the same on Windows. Examples here use POSIX shell for brevity. The Windows equivalents differ in the shell, not in envy:

POSIX	Windows
./bin/envy sync	bin\envy.bat sync
./bin/cmake (deployed wrapper)	bin\cmake.bat
~/Library/Caches/envy, ~/.cache/envy	%LOCALAPPDATA%\envy
PATH separated by :	separated by ;
envy shell zsh prints source "…/hook.zsh"	envy shell powershell prints . "…/hook.ps1"

The --platform flag on sync, deploy, and init selects which script flavors to write, not which OS you are on. A repo synced on macOS with --platform all commits working Windows wrappers. envy also disables Windows-style /flag option prefixes. A POSIX-looking absolute path is never mistaken for a flag.

Package queries

sync, install, deploy, vendor, export, and package take queries that select manifest entries. A query matches an entry's identity by dropping components, not by substring:

Query form	Matches
cmake	any namespace, any revision, so envy.cmake@r0 and local.cmake@r3
envy.cmake	that namespace, any revision
cmake@r0	that revision, any namespace. A dotted revision works too: gcc@13.2.0 matches arm.gcc@13.2.0 from envy 0.3.1 on, where earlier versions read the dot as a namespace and matched nothing
envy.cmake@r0	that identity
envy.cmake@r0{["version"]="4.2.3"}	one option variant, the full canonical key

Each query resolves to the first matching entry in manifest order, and its dependencies come along automatically. A query that matches nothing is an error. So is one that matches an entry excluded on the current platform. A filter typo fails instead of silently doing less.

Global flags

Flag	Effect
--verbose	DEBUG logging: per-package decision narrative, with timestamp and level. Excludes -q.
-q, --quiet	Warnings and errors only.
--trace[=<sinks>]	Structured machinery events for the scheduler, cache, locks, and IO. Comma-separated sinks: stderr for human-readable text, file:<path> for JSONL. Bare --trace means stderr. Independent of log level. See Logging & Tracing.
--cache-root <path>	Override the cache root. Env: ENVY_CACHE_ROOT.
--project <dir>	Walk up from <dir> instead of the current directory to find the manifest. Honored by every command that loads one: sync, install, deploy, vendor, product, package, run, export, import, use, cache, and shell. Repeatable, last value wins. The directory must exist.
-v, --version	Print version info. Alias for envy version.
-h, --help	Print help. Works per subcommand: envy sync --help.

Commands

Everyday

Command	Purpose
envy sync	Install packages and deploy product scripts. Run it after a manifest edit.
envy install	Install packages only.
envy deploy	Deploy product scripts only.
envy vendor	Restore vendored copies in the project tree.
envy product	Resolve a product to its path or value, or list all.
envy package	Install one package and print its directory.
envy run	Run your own script with envy resolvable and the project root known.

Project management

Command	Purpose
envy init	Initialize a project: manifest, bootstrap scripts, editor config.
envy use	Retarget the manifest's pinned envy version.
envy shell	Print the shell-profile line that enables shell hooks.
envy cache	Show cache location and disk usage.

Spec authoring

Command	Purpose
envy git-resolve	Resolve a remote branch or tag to a full commit hash.
envy hash	Print sha256 lines for fingerprint tables and depot indexes, or --tree for one BLAKE3 digest per directory.
envy fetch	Download one resource the way FETCH would.
envy extract	Extract an archive the way STAGE would.
envy lua	Run a Lua script inside envy's runtime.

Depot publishing

Command	Purpose
envy export	Export cached packages as depot artifacts.
envy import	Import exported artifacts into the cache.
envy merge-depot	Merge per-platform depot indexes.

Administration

Command	Purpose
envy mirror-envy	Mirror an envy release to a directory or S3.
envy version	Print version info and bundled licenses.