CLI Overview

vagaris is the Vagaris command-line client. It does three jobs:

1. Runs an instance — vagaris onboard, vagaris run, vagaris doctor, vagaris configure set up and start a local Vagaris server with an embedded PostgreSQL database.
2. Operates a company — vagaris issue, vagaris agent, vagaris approval, vagaris skills and the other control-plane groups talk to a running server's REST API.
3. Hosts governed work on your machine — vagaris dev claims a run from the server, verifies the server-issued lease, and executes a coding agent (Claude Code or Codex) inside an isolated worktree under that lease. vagaris runctl watches, pauses, resumes and cancels runs; vagaris node enrols the machine.

The package is @vagarylabs/vagaris; the installed command is vagaris. The older vagris command is kept as an alias and prints a deprecation warning on stderr before running the same command tree.

Where to start

You want to	Read
Install the binary	Install
Go from nothing to a completed task	Getting Started
Sign in to a deployed (authenticated) instance	Login
Understand what a session looks like	First Session
Run an agent on your laptop under governance	Developer Mode
Look up a command or flag	CLI Reference
Something is wrong	Troubleshooting, then Support

Shared options

Every command that talks to the server accepts the same client options (see vagaris company list --help for the canonical list):

Flag	Meaning
--api-base <url>	Base URL of the Vagaris API
--api-key <token>	Bearer token for agent-authenticated calls
--context <path>	Path to the CLI context file
--profile <name>	Context profile to use
-c, --config <path>	Path to the instance config file
-d, --data-dir <path>	Data directory root, isolating all state from the default home
--json	Print raw JSON

Company-scoped commands add -C, --company-id <id>. Where a value is not passed on the command line the CLI resolves it from environment variables and then from the active context profile — the exact precedence is on Configuration.

Exit codes

Client commands exit with a stable code so scripts can branch without parsing text: 0 success, 1 unexpected error, 2 policy refusal, 3 authentication, 4 conflict, 5 not found, 6 timeout, and higher codes for lease, node, ceiling, protocol and usage errors. The full table is on Troubleshooting.

Two legacy names you will see

• vagris — the previous command name. Still installed, still works, warns on stderr.
• PAPERCLIP_* — the previous environment-variable prefix. Every variable is read under the canonical VAGARIS_* first, then VAGRIS_*, then PAPERCLIP_*; see Environment Variables.