Context

vagaris context manages profiles — named, local bundles of apiBase, companyId and (the name of) an API-key environment variable, stored in a context.json next to your repo (or under your data directory). Every other client command reads its defaults from whichever profile is in effect, in the precedence documented on the CLI Overview: an explicit flag, then an environment variable, then the profile.

Selection precedence — explicit and CI-safe

Two subcommands, show and clear, act on "the profile in effect" rather than on one you name outright. Both resolve it in this order, and refuse rather than guess if none of these apply:

--profile <name> on the invocation itself.
VAGARIS_PROFILE (older spellings VAGRIS_PROFILE, PAPERCLIP_PROFILE are also read) in the invocation's environment.
the persisted "current" profile left by an earlier context use — only when the invocation is interactive (both stdin and stdout are a TTY).

A non-interactive invocation — a CI job, a piped script, a cron run — with none of the first two never falls through to step 3. It refuses immediately, before making any request:

$ vagaris context show
Error: 'vagaris context show' refuses to guess a profile in a non-interactive invocation.
Pass --profile <name> or set VAGARIS_PROFILE explicitly — the profile a prior
interactive 'vagaris context use' left active is not inherited here.

This is deliberate: a profile switched interactively on a developer's machine, or on a shared CI runner, must never become the silent default for a later unrelated invocation — the ambient-context anti-pattern named in the CLI's do-not-build register. Pass --profile (or set VAGARIS_PROFILE) in scripts; reserve bare vagaris context show for a terminal you're sitting at.

context list and context use are unaffected — list enumerates every profile regardless (there's nothing to guess), and use always takes the profile as a required argument (there's nothing ambient to inherit; it's the thing step 3 above inherits from). context export sidesteps the question by defaulting to "every profile" rather than "the current one" — see below.

Inspect

vagaris context list
vagaris context show [--profile <name>]

list prints every profile and marks which one is current. show prints the resolved profile's local fields — apiBase, companyId, whether an API-key env var is configured — and, when the server at that apiBase is reachable, the live session it resolves to (GET /api/session: identity, projection, authority and server context). The session block degrades gracefully rather than failing the whole command: an unreachable or erroring server yields sessionUnavailable: { code, class, reason } and session: null, since show is also the tool for inspecting local profile configuration before a server exists.

$ vagaris context show --profile work --json
{
  "contextPath": "/Users/you/repo/.vagris/context.json",
  "currentProfile": "work",
  "profileName": "work",
  "profile": { "apiBase": "http://localhost:3100", "companyId": "company-1" },
  "profiles": { "work": { "...": "..." }, "default": {} },
  "session": {
    "identity": { "type": "board", "id": "user-1", "name": "Ada Lovelace", "email": "ada@example.com", "source": "board_key" },
    "authority": { "authenticated": true, "tier": "act", "...": "..." },
    "...": "..."
  }
}

Switch

vagaris context use <profile>

Sets the persisted "current" profile. This is what step 3 of the precedence above reads — and, per that rule, only an interactive invocation of another command will fall back to it. A script should never rely on context use having been run first; pass --profile (or VAGARIS_PROFILE) to every command it runs.

Configure

vagaris context set --profile work --api-base http://localhost:3100 --company-id <id> --api-key-env-var-name VAGARIS_AGENT_TOKEN [--use]
vagaris context link --profile work --org <id> --project <id> --repo <url> --branch <name>

set writes apiBase/companyId/the API-key env var name (never a key value — the store never holds one) onto a profile, and --use also makes it current. link records local pointers to an existing organization, project and repository — it creates no server-side rows; see the file's own note when you run it.

Clear

vagaris context clear [profile] [--profile <name>] [--all] [--json]

Resets a profile's stored fields (apiBase, companyId, the API-key env var name, the link block) back to empty, without removing the profile entry itself or touching any other profile. Naming the profile — positionally or with --profile — is always explicit and works from a script; omitting it falls under the precedence rule above and is refused non-interactively. --all resets the entire context file back to defaults (every profile removed) regardless of interactivity, since it names no ambiguous target.

vagaris context clear work            # explicit — works anywhere
vagaris context clear --all           # explicit wipe — works anywhere
vagaris context clear                 # refused in CI; falls back to "current" only in a terminal

Export

vagaris context export [--profile <name>] [--json]

Prints the context file for backup or sharing, with credential metadata excluded: each profile reports hasApiKeyEnvVar: true|false rather than the configured env var's name, and the store never contains a key value to begin with. Omitting --profile exports every profile — a deterministic default, not an inherited one, so export needs no interactivity check. Passing --profile exports just that one, equally redacted.

Environment variables

Variable	Effect
`VAGARIS_CONTEXT` (older: `VAGRIS_CONTEXT`, `PAPERCLIP_CONTEXT`)	Overrides the context file path (see `--context` and Environment Variables).
`VAGARIS_PROFILE` (older: `VAGRIS_PROFILE`, `PAPERCLIP_PROFILE`)	Names the profile explicitly, satisfying step 2 of the precedence rule — the CI-friendly way to select a profile without persisting a "current" one or repeating `--profile` on every command.

Selection precedence — explicit and CI-safe​

Inspect​

Switch​

Configure​

Clear​

Export​

Environment variables​