Install

Requirements

• Node.js 20 or newer (the package runs on Node; the Homebrew formula depends on node).
• macOS or Linux. vagaris node doctor reports other platforms as untested.
• git if you intend to use vagaris dev, which creates a git worktree per run.

npm

npm install -g @vagarylabs/vagaris
vagaris --version

npm install -g is also what vagaris update and vagaris rollback run under the hood, so keeping the global install on npm keeps those commands working.

To try a command without installing globally:

npx @vagarylabs/vagaris doctor --help

Homebrew

The formula is Vagaris, published from the Cramraika/homebrew-vagaris tap. It installs the same npm tarball and links two commands, vagaris and the legacy alias vagris:

brew tap Cramraika/vagaris
brew install vagaris
vagaris --version

Verify

vagaris --version
vagaris --help
vagaris doctor --json

vagaris doctor reports a failing "Config file" check on a machine that has never been onboarded — that is expected before Getting Started; the JSON shape is documented on Doctor.

Where files go

The CLI keeps its state under one home directory:

Path	Contents
~/.vagris/	Default home. If a ~/.paperclip/instances directory already exists from an earlier install, that directory is used instead.
~/.vagris/instances/default/config.json	Instance configuration
~/.vagris/instances/default/.env	Generated secrets such as PAPERCLIP_AGENT_JWT_SECRET (mode 0600)
~/.vagris/instances/default/{db,logs,data}	Embedded PostgreSQL data, logs, storage and backups
~/.vagris/context.json	CLI context profiles
~/.vagris/auth.json	Board-login credential store (tokens themselves live in the OS keychain)
~/.vagris/node-identity.json	This machine's node attestation key, written by vagaris node enroll
~/.vagris/update-history.json	The previous version recorded by vagaris update, used by vagaris rollback

Set VAGARIS_HOME to move the whole tree, VAGARIS_INSTANCE_ID to select an instance, or pass --data-dir <path> on any command to isolate a run completely. Details on Configuration.

The legacy command

vagris remains installed beside vagaris. It runs identical code and writes one line to stderr:

Warning: 'vagris' is deprecated; use 'vagaris' instead.

Scripts that parse stdout are unaffected; update them to vagaris at your convenience.

Uninstall

vagaris uninstall removes the CLI's own files and revokes its stored credential; it deliberately leaves other tools' directories alone. See Updates.