Documentation

The API, CI and editors

Everything in the CLI is available as JSON, and everything about signing in has an answer that needs no browser.

`--json`, and where it goes

--json replaces the human output with one JSON document on standard output; narration moves to standard error, so a script always gets exactly one document to parse. It is a global flag and must come before the command — graph --json status, never graph status --json, which argparse rejects with exit 2.

Command	What `--json` does
`whoami` `projects` `config` `status` `health` `check` `drift` `tasks` `run`	One JSON document instead of the human output
`login` `logout` `link` `setup`	The outcome as data — `setup` gives the whole step-by-step sequence
`agent`	Turns off the live view and prints one machine-readable line per finished task. The headless-runner form
`undo`	Ignored — it stays interactive, and `--yes` is what a script wants
(bare) `graph --json`	The command list, because a script asking with no command wants the surface

The same `status` you would read on screen, as data.

graph --json status  | jq -r '.runner_connected'
graph --json tasks   | jq -r '.tasks[] | select(.status=="pending") | .id'
graph --json health  | jq '.findings | group_by(.severity) | map({(.[0].severity): length})'

Exit codes

Code	Means	What CI should do
`0`	Passed	Continue
`1`	Failed — a health error, drift, or a command that could not do what was asked	Fail the build
`2`	Could not run — the deployment was unreachable, or the credentials were refused	Fail the build
`130`	Interrupted (Ctrl-C)	—

2 exists so a gate that could not run is never mistaken for a gate that passed. Treating it as success is how a check quietly stops checking.

Credentials for a machine

There is nobody in CI to open a browser, so the environment is the way in. Both of these are read before anything stored on disk, so a container can override a mounted credential without editing it.

Variable	What it is
`VIPL_API_KEY`	An API key from Account → API keys. The usual choice for CI
`VIPL_TOKEN`	An identity token, when you already have one
`VIPL_API`	The deployment, if it is not the default
`VIPL_API_TOKEN`	The shared token of a locked self-hosted deployment. Not a user credential

yaml

- name: Architecture gate
  env:
    VIPL_API_KEY: ${{ secrets.GRAPHLIT_API_KEY }}
  run: |
    curl -fsSL https://graphlit.co/install.sh | sh -s -- --no-setup
    graph check

Run it in the checkout. graph check sends the .vipl/graph.json next to it, so a repository with the graph committed needs no project argument and no link step.

There is no --project flag on check, drift, health or status: the project is a positional argument, and it is optional because the folder's link already names one.

graph check                      # the linked project, from this folder
graph check "Recipe Box"         # by name
graph check --path ~/code/app    # a checkout somewhere else

How the client talks to the deployment

The CLI calls the API directly over HTTPS, sending the identity token on x-vipl-identity or an API key on x-vipl-api-key.
The browser never does. Everything the dashboard fetches goes same-origin through its own proxy, which checks your session and only then attaches the API's credential — so no server secret is ever compiled into a page.
A 401 is answered as 401, with a header saying which credential was refused, so an expired session reads as you are signed out rather than as a parse error.
TLS goes through the system trust store first, and falls back to a bundled root set only after verification has actually failed — never before, because a machine behind corporate TLS interception has its own root in the system store and the bundle does not contain it.

Inside your coding agent

Graphlit also ships an MCP server, so an agent in your editor can drive the same loop without you typing commands. Thirteen tools, and the count is a deliberate ceiling — a token-heavy MCP server is one people turn off.

Tool	Does
`vipl_interpret_sketch`	A drawing → a typed graph. Merges into what already exists rather than replacing it
`vipl_expand_plan`	Infers the architecture that was not drawn, and asks clarification questions instead of guessing
`vipl_get_graph` / `vipl_update_graph`	Read it; write it, with the origin rules enforced
`vipl_import_repo`	Brownfield scan of an existing codebase into a graph
`vipl_plan_tasks`	The ordered plan, full or delta
`vipl_next_task` / `vipl_complete_task`	The build loop, including the task's graph neighbourhood — what to reuse and what not to break
`vipl_check_drift`	Hash-check every mapping against the working tree
`vipl_scan_bugs`	The defect scan
`vipl_status`	Where the project stands