Reference

Exit codes, environment variables, the composer.json config keys viv reads, the files it writes, and every global option.

Exit codes and the stderr/stdout contract

viv's exit codes, defined in src/main.rs:

0 — success.
1 — a command failed (an anyhow::Error bubbled up from the command, or an outdated/audit check that isn't a lock mismatch or vulnerable package), or the command line itself was invalid: a bad flag, a missing required argument, an unknown subcommand (cli_error).
2 — the dependency resolver couldn't find a solution (resolver_error).

1 covers both a command that failed and a command that was never recognised as valid; 2 is reserved for the resolver alone, so a script can tell "no solution exists" from "you typed the command wrong" (#236). outdated --strict-style checks that report "something out of date" use 1 rather than a dedicated code; treat any non-zero exit as failure unless a command's own docs say otherwise.

stderr is for humans: warnings, confirmation prompts and diagnostics can reword between releases without notice. stdout for show, why, validate and the other commands that mirror Composer's plain-text output is contractual and covered by the same guarantee as vendor/ and composer.lock.

Environment variables

viv's own:

Variable	What it does
`VIV_METADATA_TTL`	Same as `--metadata-ttl` on `update`, `add` and `rm`: skip revalidating a package's cached metadata while it's younger than this many seconds. The flag wins when both are set. (`src/update.rs`)
`VIV_COMPOSER_PATH`	Points the `composer` shim at the real Composer binary, for when it isn't first on `PATH`. (`src/bin/composer.rs`)
`VIV_SHIM_STRICT`	Set to make the `composer` shim hard-error on a command or flag it doesn't understand, instead of falling back to the real Composer. (`src/bin/composer.rs`)
`VIV_MAX_INFLATED_BYTES`	Overrides the computed cap on how many bytes a single archive may inflate to, viv's guard against a zip bomb. (`src/store.rs`)

A few more (VIV_TEST_NOW, VIV_TEST_EXTRACT_WORKERS, VIV_TEST_SCAN_WORKERS) exist only to make viv's own test suite deterministic; they're not a documented interface.

Composer's own, that viv also reads:

Variable	What it does
`COMPOSER_HOME`	Where viv looks for `auth.json` and `config.json`, same as Composer: `$COMPOSER_HOME` if set, else `~/.composer` if that directory already exists, else `$XDG_CONFIG_HOME/composer`. (`src/auth.rs`)
`COMPOSER_AUTH`	JSON credentials, merged over the composer home's and the project's `auth.json` — highest precedence of the three. (`src/auth.rs`)
`COMPOSER_DISABLE_NETWORK`	Any value but unset, empty or `0` acts like `--offline`. (`src/main.rs`)
`COMPOSER_NO_SECURITY_BLOCKING`	Any value but unset, empty or `0` acts like `--no-blocking`: allow a version with a known security advisory during `update`, `add` or `rm`. (`src/update.rs`)
`XDG_CACHE_HOME`	Where viv's store lives, as `$XDG_CACHE_HOME/vivace`; falls back to `~/.cache/vivace`. (`src/update.rs`)
`XDG_CONFIG_HOME`	Falls back into `COMPOSER_HOME`'s own default, above, when neither `COMPOSER_HOME` nor a legacy `~/.composer` is present. (`src/auth.rs`)
`COLUMNS`	Terminal width `viv show` wraps its output to; defaults to 80 when unset or not a number. (`src/show.rs`)

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

`composer.json` config keys

viv reads this subset of the root composer.json's config block (src/lock.rs, the Config struct):

Key	What it does
`autoloader-suffix`	The suffix on the generated `ComposerAutoloaderInit`/`ComposerStaticInit` class names.
`platform-check`	Whether and how strictly `platform_check.php` verifies the PHP version and extensions at runtime.
`vendor-dir`	Where packages install (default `vendor`).
`prepend-autoloader`	Whether the generated autoloader registers itself with `prepend: true`.
`bin-dir`	Where `vendor/bin` proxies are written; defaults to `<vendor-dir>/bin` when unset.
`bin-compat`	How `vendor/bin` proxy scripts are generated for compatibility across platforms.
`optimize-autoloader`	`install -o`'s default: also classmap-scan PSR-0/PSR-4 directories.
`classmap-authoritative`	`install -a`'s default: classmap-only autoloading, skipping the PSR fallback.
`apcu-autoloader`	`install --apcu-autoloader`'s default.
`apcu-autoloader-prefix`	The default value for `install --apcu-autoloader-prefix`.
`use-include-path`	Whether the generated loader also searches PHP's include path.
`secure-http`	`false` lets dist/repository URLs downgrade to plain `http` (Composer defaults this `true`).
`allow-plugins`	Which `composer-plugin` packages viv treats as enabled — see Plugins.
`preferred-install`	`dist`/`source` per package; the project's setting is merged with the Composer home's own `config.json`.
`audit.ignore`, `audit.abandoned`	`viv audit`'s ignore list and its abandoned-package policy.
`audit.block-insecure`, `audit.block-abandoned`	Whether a version with a known advisory, or an abandoned package, is filtered from the resolver pool during `update`, `add` or `rm`.

A config key not in this table is ignored: viv doesn't read it, and doesn't warn that it's unread either.

Files viv writes in `vendor/`

vendor/autoload.php, and in vendor/composer/:

File	When
`autoload_namespaces.php`, `autoload_psr4.php`, `autoload_classmap.php`, `autoload_static.php`, `autoload_real.php`	always
`autoload_files.php`	any `files` entry, else deleted
`platform_check.php`	`config.platform-check` not `false` and at least one PHP or ext requirement, else deleted
`ClassLoader.php`, `InstalledVersions.php`, `LICENSE`	verbatim copies from Composer (MIT); vivace embeds them from `src/autoload/templates/`
`installed.json`, `installed.php`	always
`vendor/bin/*`	packages with `bin`, per `config.bin-compat` (`src/bin.rs`)

No .gitignore is written. Files are only rewritten when their bytes change.

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
  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 `scripts` entry from the root composer.json
  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
  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