Reference

One page per command, generated from its own --help output so the flags here never drift from the binary.

Global options

Fast composer install from composer.lock

Usage: viv [OPTIONS] <COMMAND>

Commands:
  init           Write a composer.json for a new project and stop (#143): no interactive question flow, defaults inferred from git and the directory. `--require`/`--require-dev` chain into the same resolve/lock/install `viv add` runs (`--no-install` opts out)
  new            Start a project in a directory that doesn't exist yet (#139): a bare directory name runs `init`'s own defaults inside it; a `vendor/package[:constraint]` spec downloads that package's dist as a skeleton and installs it there. `create-project` is Composer's own name, kept as an alias along with its `vendor/package dir constraint` three-positional shape (prefer `vendor/package:constraint` instead) [alias: create-project]
  install        Install packages from composer.lock
  update         Resolve composer.json, write a composer.lock (full or partial update) and install (`--no-install` opts out)
  update-lock    `update --lock`'s own first-class subcommand (#86): re-derive `composer.lock` from itself without solving or installing
  add            Add a dependency to composer.json, resolve it and install (`--no-install`/`--no-update` opt out) [alias: require]
  rm             Remove a dependency from composer.json, resolve the rest and install (`--no-install`/`--no-update` opt out) [alias: remove]
  dump-autoload  Regenerate the autoload files and `vendor/bin` from an already installed `vendor/`, without fetching or linking
  normalize      Normalize composer.json's key order and formatting, a native `composer normalize` (ergebnis/composer-normalize)
  cache          Cache maintenance: prune stale entries, or remove the cache outright
  lock           Lock file maintenance: translate an existing `composer.lock` into chapter 1's `viv.lock` (#273), without re-solving, or merge one as a git merge driver (#275)
  audit          Check installed (or locked) packages for security vulnerability advisories and abandoned packages
  show           List installed packages, or inspect one (`--tree`/`-t` for the require tree)
  tree           `show --tree`'s spelling (#86)
  why            `composer why`/`depends`'s alias (#86): `tree --invert`, listing which installed packages require `package`
  outdated       List installed packages with a newer version available (`show --latest --outdated`)
  validate       Validate a composer.json (and composer.lock) against Composer's own hand-written rules
  x              Install (if needed) and run a package's bin in an isolated, content-hashed env, npx-style (#85)
  run            Run a script, a vendor/bin binary or a PATH command on the project's PHP
  exec           Exec a `vendor/bin` binary with `vendor/bin` prepended to `PATH`
  diagnose       Environment and configuration report to paste into a bug report: cache, auth sources (names only), PHP/git/Composer, platform packages and the plugin decision per lock entry
  workspace      `list` (#276): discover `extra.viv.workspace` members and report inter-member requirements. `init`/`add` (#315): write the aggregate root composer.json from member glob patterns and resolve/install
  php            Download a static-php-cli PHP build and pin `config.platform.php` to it (#337), or list what's already installed
  isolate        Prefix a plugin's bundled dependency tree with php-scoper so it can coexist with the site's own copy of the same library (#351): `<package>` adds it to `extra.viv.isolate` and isolates it, `--rm <package>` removes it and relinks the plain archive, `--list` prints every isolated plugin and its prefix
  completions    Print a shell completion script
  help           Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose                Raise logging to debug
      --cache-dir <CACHE_DIR>  Store location (default `$XDG_CACHE_HOME/vivace`, or `~/.cache/vivace`)
      --offline                Fail fast on any request instead of connecting: install errors, naming every package not already in the store; update solves from cached repository metadata only, erroring on an uncached package. Also set by `COMPOSER_DISABLE_NETWORK` (any value but unset, empty or `0`; Composer's own git-priming `prime` value is not special-cased here, since neither `install` nor `update` touch a git source)
  -h, --help                   Print help
  -V, --version                Print version

Commands

Command	What it does
viv init	Writes a new project's composer.json and stops, no interactive prompts.
viv new	Starts a project from a bare name or a `vendor/package` skeleton.
viv install	Installs the exact versions composer.lock records.
viv update	Resolves composer.json, writes the lock and installs.
viv add	Adds a dependency to composer.json, resolves it and installs.
viv rm	Removes a dependency from composer.json, resolves the rest and installs.
viv dump-autoload	Regenerates the autoload files from an already-installed vendor/.
viv normalize	Tidies composer.json's key order and formatting.
viv cache	Prunes, cleans or reports the size of the shared store.
viv audit	Checks installed or locked packages for security advisories and abandoned packages.
viv show	Lists installed packages, or inspects one.
viv tree	Shorthand for `show --tree`.
viv why	Lists installed packages that require the named package.
viv outdated	Flags installed packages with a newer version available.
viv validate	Checks composer.json (and composer.lock) against Composer's rules.
viv x	Installs and runs a package's binary in an isolated, cached environment.
viv run	Runs a scripts entry from the root composer.json.
viv exec	Runs a vendor/bin binary with vendor/bin prepended to PATH.
viv php	Downloads a static-php-cli build and pins config.platform.php to it.
viv diagnose	Prints an environment and configuration report for a bug report.
viv lock	Converts, merges or exports a viv.lock/composer.lock pair.
viv workspace	Discovers and manages a monorepo's member packages.
viv isolate	Prefixes a plugin's bundled dependencies so they stop clashing with the site's own.
viv completions	Prints a bash, zsh or fish completion script.

Environment variables

viv's own:

Variable	What it does	Commands
`VIV_METADATA_TTL`	Same as `--metadata-ttl`: skip revalidating cached metadata younger than this many seconds; the flag wins when both are set.	update, add, rm
`VIV_MAX_INFLATED_BYTES`	Overrides the computed cap on how many bytes a single archive may inflate to, viv's zip-bomb guard.	install, update, add, rm
`VIV_COMPOSER_PATH`	Points the `composer` shim at the real Composer binary, when it isn't first on PATH.	the composer shim
`VIV_SHIM_STRICT`	Set to make the `composer` shim hard-error on an unrecognised command or flag, instead of falling back to the real Composer.	the composer shim
`VIV_VIA_SHIM`	Set by the shim itself so `install --adopt`'s own detection can tell it's running under it.	install
`VIV_PHP_DIST_URL`	Overrides the static-php-cli build base URL `php install` fetches from.	php install

Composer's own, that viv also reads:

Variable	What it does	Commands
`COMPOSER_HOME`	Where viv looks for auth.json and config.json.	all
`COMPOSER_AUTH`	JSON credentials, merged over the Composer home's and the project's auth.json.	all
`COMPOSER_DISABLE_NETWORK`	Any value but unset, empty or `0` acts like `--offline`.	all
`COMPOSER_NO_SECURITY_BLOCKING`	Any value but unset, empty or `0` acts like `--no-blocking`.	update, add, rm
`XDG_CACHE_HOME`	Where viv's store lives, as `$XDG_CACHE_HOME/vivace`; falls back to `~/.cache/vivace`.	all
`XDG_CONFIG_HOME`	Falls back into COMPOSER_HOME's own default when neither it nor a legacy `~/.composer` is present.	all
`COLUMNS`	Terminal width `viv show` wraps its output to; defaults to 80 when unset or not a number.	show, tree, why

COMPOSER_CACHE_DIR is Composer's own cache location variable; viv doesn't read it: use XDG_CACHE_HOME or --cache-dir instead.

Exit codes

0 on success. A dependency-resolution failure (update, add, rm, install, workspace init/add) exits 2, matching Composer's own ERROR_DEPENDENCY_RESOLUTION_FAILED; every other error, including a bad flag, exits 1. audit and validate use their own exit codes to report a finding rather than a failure to run; see each page.

Edit this page on GitHub