Skip to main content

First Session

A "session" in the CLI is nothing more than a shell with a resolved context: which server, which credential, which company. This page shows how that resolution works so the rest of the documentation makes sense.

Context profiles​

Profiles live in ~/.vagris/context.json (or the path in VAGARIS_CONTEXT, or the nearest .vagris/context.json found walking up from the current directory).

vagaris context set --api-base http://localhost:3100 --company-id <company-id> --use
vagaris context list
vagaris context show
vagaris context use default
  • context set writes apiBase, companyId and apiKeyEnvVarName onto a profile (--profile <name>, default: the current one). --use also activates it.
  • context list prints every profile with its apiBase, companyId and apiKeyEnvVarName, and marks the current one.
  • context show prints the full store and the resolved profile. --profile inspects a different one without switching.
  • context use <profile> switches the active profile.

context link records local pointers to entities that already exist on the server — organization, project, repository and branch — without creating anything server-side:

vagaris context link --org <org-id> --project <project-id> --repo git@github.com:acme/app.git --branch main

Keep separate profiles per instance (for example local and prod) and switch with context use.

Data directory isolation​

--data-dir <path> on any command points the whole CLI — home, instance, config, context — at a different directory. It is the cleanest way to run a throwaway instance:

vagaris run --data-dir ./tmp/vagaris-dev
vagaris doctor --data-dir ./tmp/vagaris-dev

If you also pass --config or --context, those explicit paths win over the derived ones.

Reading output​

Every client command prints a human layout by default and raw JSON with --json. Lists are printed one record per line as key=value pairs, with identifier, id, name, status, priority, title and action first when present. Objects are pretty-printed JSON either way, so --json mainly matters for lists and for commands that add a label line.

vagaris issue list --status todo,in_progress
vagaris issue list --status todo --json | jq '.[].identifier'

Errors from the API are printed as API error <status>: <message> on stderr and mapped to an exit code (see Troubleshooting).

Interactive versus non-interactive​

The CLI treats a session as interactive only when both stdin and stdout are terminals. That decides:

  • whether a 401/403 triggers the browser login flow (Login);
  • whether vagaris doctor --repair asks before each repair (--yes skips the prompt; --json never repairs);
  • whether vagaris run will fall into onboarding when no config exists (non-interactive: it exits 1 and tells you to run vagaris onboard);
  • whether vagaris agent local-cli --install-skills may ask for consent (non-interactive: it requires --yes or refuses).

A typical session, end to end​

vagaris context use local
vagaris dashboard get
vagaris issue list --status in_progress
vagaris approval list --status pending
vagaris runctl history
vagaris runctl attach --run-id <run-id>

dashboard get is the company summary; approval list --status pending is what is waiting on you; runctl attach follows a live run's transcript read-only until it ends, times out (default 30 minutes) or you press Ctrl+C.

Continue with Developer Mode to host runs locally, or Approvals to act on what agents ask for.