Exec and Which
yerd exec runs PHP tools under the PHP version a site uses, rather than the global default, and Node tools (node, npm, npx) under the project's selected Node release (see Node resolution). yerd which reports which binary that would be, without running anything.
A site's version governs how it is served, but the bare php and composer shims always resolve to the global default. Inside a site on 8.3 while your default is 8.5, php artisan and composer install therefore run on a different PHP than the site's own web requests. These two commands close that gap; the shims themselves are unchanged.
Like coverage, path, and elevate, neither command maps to an IPC request: exec replaces itself with PHP directly (inheriting your stdin/stdout/stderr, arguments, and exit code), and which only prints a path. (Attempting to route either over IPC is an explicit usage error.) The one daemon round-trip is the site lookup behind the scenes.
yerd exec [--site <NAME>] <php|composer|node|npm|npx> [ARGS...]
yerd which [--json] [--site <NAME>] <php|node|npm|npx>| Command | Description |
|---|---|
yerd exec php [ARGS...] | Run the site's PHP CLI, passing ARGS to PHP. |
yerd exec composer [ARGS...] | Run the bundled Composer phar under the site's PHP. |
yerd exec --site <NAME> … | Use the named site's version instead of the current directory's. |
yerd which php | Print the absolute path of the PHP binary yerd exec would use. |
yerd which --json php | Print {path, version, site, source} for that binary. |
| Flag | Description |
|---|---|
--site <NAME> | Resolve against this site instead of the current directory. Never falls back: an unknown name is an error. |
--json | which only. Emit the resolved path plus its version and origin as JSON. |
cd ~/Sites/my-app # served on 8.3
yerd exec php -v # PHP 8.3.x
yerd exec php artisan migrate
yerd exec composer install # the bundled phar, under 8.3
yerd exec --site blog php -v # blog's version, from anywhere
yerd which php # /…/php/php-8.3/bin/php
yerd --json which php # {"path":"…","version":"8.3","site":"my-app","source":"site"}which shares exec's resolution path exactly, so it can never print a path that exec wouldn't actually run.
Resolution
| Where you run it | Which PHP |
|---|---|
| Inside a registered site | that site's stored version |
| Outside every site | the global default |
With --site <NAME> | that site's stored version, from anywhere |
Nested sites resolve to the most specific match, and matching is on the site's project root, not its served root - so a Laravel site served from public/ still resolves from the project root, where artisan and composer.json live.
Every registered site resolves to a concrete version, so source is site even for a site you never explicitly pinned - there is no "unpinned" state. A linked site snapshots the global default at link time and does not move when you change the default afterwards; a parked site follows the current default unless pinned. See Site-aware CLI for why, and how to move a site's version deliberately.
In --json mode, source is site when the version came from a site and default otherwise, with site then null.
Node resolution
For node, npm, and npx, both commands share this priority:
- The nearest
.nvmrcor.node-versionin the current directory or its parents, stopping at the registered project's root. Within one directory.nvmrcwins; otherwise the nearest directory wins. - The saved preference from
yerd node use <version> --site <name>. - The global default from
yerd node use <version>.
Outside registered sites, the nearest project file in any parent applies. With --site, the search starts at that named site's project root, so its root project file applies from any caller directory. Nested registered sites use the most specific root. A subdirectory project file overrides a root file within its project, so a nearer .node-version beats a farther .nvmrc.
.nvmrc and .node-version accept a single numeric major, minor, or exact release with an optional v prefix, plus node (newest installed release), lts/* (newest installed release recorded as LTS), and lts/<codename> such as lts/iron (newest installed release of that LTS line, codename case-insensitive). Leading and trailing whitespace is ignored. default, comments, and other nvm syntax are unsupported and fail clearly. A legacy single-version installation ({data}/tools/node) counts as LTS, since that installer only ever fetched the latest LTS, so lts/* can select it too; it has no recorded codename, so lts/<codename> cannot. The aliases also work with yerd install tool node <alias> and yerd node use <alias>.
An empty, unreadable, unsupported, or unmatched project file is an error (exit 2); it never falls through to a site preference or default. Missing installed versions also fail with an installation hint. A missing yerd.toml counts as an empty config; other config I/O failures exit 74. Node project resolution requires the daemon's live site list: an unreachable daemon exits 69, including outside sites. PHP's existing warning and default fallback behavior remains unchanged.
npm and npx run their bundled entry point through the selected Node interpreter. The selected release's bin directory is prepended to PATH, so spawned node, npm, and npx processes use the same release. which reports the node binary or npm/npx entry point and, with --json, an exact version and source of nvmrc, node-version, site, or default.
The desktop app's site inspector sets the same saved preference and warns when a project file overrides it.
Passthrough behaviour
Everything after the tool is handed straight to that tool, so no -- separator is needed - and yerd's own flags must come before it:
yerd exec --site blog php -v # --site is yerd's
yerd exec composer show --json # --json is Composer's
yerd exec php -r 'echo PHP_VERSION;'-h/--helpgo to the tool, soyerd exec composer --helpprints Composer's help, not yerd's. Useyerd help execfor this command's own help. This differs fromcoverage, where a leading--helpis yerd's.- The global
--jsonis not interpreted byyerd exec- it reaches the tool, sinceyerd exec composer show --jsonhas to produce Composer's JSON. Along withcoverage, this is an exception to the "--jsonon every command" note in the overview.yerd which --jsonis unaffected:whichruns nothing, so--jsonis yerd's there. yerd execexits with the tool's own exit code, so it composes in CI exactly like the interpreter it wraps.
yerd exec composer runs the same bundled phar the composer shim does, just under the site's PHP - and additionally points PHPRC at that version's generated CLI ini.
Failure modes
Both commands fail rather than quietly running the wrong PHP:
- A stored-but-uninstalled version is an error (exit
2), not a silent fallback to the default - that silent mismatch is what these commands exist to prevent. Install it (yerd install php 8.3) and retry. --sitenever falls back. An unknown name is a usage error (exit2); a daemon that isn't running to resolve it exits69. Naming a site is an instruction, not a hint.- Without
--site, an unreachable daemon just means "not inside a site" for PHP (php,composer): the global default is used, with a warning on stderr, since inside a site that would otherwise silently resolve to the wrong version. Node commands (yerd exec node|npm|npx,yerd which node|npm|npx) need the daemon's site list and exit69instead, even outside a site. - Unix only. Both commands are available on macOS and Linux.
See Exit codes for the full table.
See also
- PHP versions guide - the narrative version of this page.
- PHP - installing versions, the global default, and pinning a site.
- Tooling - the
composershim and the rest of the shim directory. - Coverage - the other passthrough command.