Documentation

Files, settings and environment

Short, and worth reading once: most confusing behaviour is a value coming from a layer you forgot about.

On your machine

Path	What
`~/.local/bin/graph`	The binary. `graphlit` is a link to the same file
`~/.vipl/credentials.json`	One entry per deployment. Mode 600
`~/.vipl/config.json`	Settings: what `graph config` writes
`~/.vipl/links.json`	Which folders on this machine are attached to which project
`~/.vipl/update-check.json`	When the once-a-day version note last ran

VIPL_HOME moves the whole directory, which is how the test suite never touches a real one.

In a project

Path	What	Commit
`.vipl/link.json`	Project id and deployment. No secrets	Yes
`.vipl/graph.json`	The Software Graph	Yes
`.vipl/tasks.json`	The plan and each task's status	Yes
`.vipl/node_file_map.json`	Node → files, with a content hash each. What drift compares	Yes
`.vipl/health.json`	Findings, with a fingerprint each so a known one stays known	Yes
`.vipl/planned_graph.json`	The baseline a delta plan is diffed against	Yes
`.vipl/history/`	Previous graph versions	Optional
`.vipl/runs/`	Records of builds that ran here	No
`.vipl/agent.lock`	Held while a runner is serving this folder	No

Environment

Variable	Effect
`VIPL_API`	The deployment. Outranks `graph config api`. Not `VIPL_API_URL`. That spelling was in `graph config`'s own source column while nothing read it, and is now gone
`VIPL_API_KEY`	An API key. Read before anything stored on disk
`VIPL_TOKEN`	An identity token. Read before anything stored on disk
`VIPL_API_TOKEN`	The shared token of a locked self-hosted deployment. Not a user credential
`VIPL_HOME`	Move the credential and settings directory
`VIPL_COLOR`	`auto` · `always` · `never`. Outranks `graph config color`
`NO_COLOR`	Any value turns colour off, as it does everywhere else

Which layer wins

For any setting, in this order. The first one that has a value decides:

01The flag you just typed.
02The environment variable, where one exists for that setting. graph config names it in the source column, so you can see which layer won.
03`~/.vipl/config.json`, which is what graph config writes.
04The built-in default.

graph config prints the winning layer beside every value, and warns you when you set something that is being overridden. That column is there because configuration that appears to be ignored is otherwise invisible.

And how the deployment is decided

Slightly longer, because a folder can disagree with an account:

01--api on the command line.
02VIPL_API.
03The folder's .vipl/link.json.
04The account you are signed in to.
05The built-in default (https://graphlit.co).

graph setup reports which of these it used when something goes wrong, so the product is looking at the wrong host is a visible answer rather than a guess.