Skip to content

Documentation

When something is wrong

Start with `graph status`. It answers most of this page in four lines and needs no page load.

The deployment, the account, the terminal, the plan.

`graph: command not found`

The install worked and your shell has not noticed. Open a new terminal — the installer appended the PATH line to your rc file, and the shell you ran it in was already started. If it persists, check that ~/.local/bin is on PATH and that ~/.local/bin/graph exists.

Everything answers 401

Ask the machine, not the server: graph whoami makes no network call and will tell you whether there is a credential here at all.

  • Nothing listed — run graph login.
  • The wrong account — graph logout then graph login, or pass --api for the deployment you meant.
  • The right account, still refused — the session has been revoked, or the key was rotated. Log in again.
  • Only in CI — VIPL_API_KEY is unset or the secret is empty. An empty variable and an absent one look identical from inside a container.

Execute does nothing

In order, and each one is a five-second check:

01

Is a terminal connected?

The board's indicator says Terminal or No terminal, and graph status says the same thing. If not, run graph agent in the linked folder.

02

Is it connected to *this* project?

graph status --all lists every linked folder on the machine and which are being served. A runner in the wrong folder is the commonest cause.

03

Is the task unblocked?

Execute is only offered when everything a task depends on is done. graph tasks prints waiting on t00N under anything blocked.

04

Is an earlier task stuck on `running`?

A runner killed mid-build can leave a task claimed, and because Execute needs dependencies done, one stuck row blocks the rest of the plan. graph undo in the folder that ran it puts the task back to pending.

`a second agent is already serving this folder`

Deliberate: two agents editing one working tree is a corrupted checkout, not parallelism. Find the other terminal and stop it. If it is genuinely gone — a crash, a closed laptop — delete .vipl/agent.lock and start again.

A build failed on scope

It changed files the task does not own: … is the guard doing its job, not the build breaking. The work is a commit; git show <sha> shows it. If the extra file genuinely belongs to that task, map it to the node and run again. If not, graph undo.

`graph drift` always says in sync

You are on a client older than 0.1.5. Up to 0.1.3 it read response fields the API does not send, so every report printed ✓ in sync and exited 0 no matter what had changed. Replace it — curl -fsSL https://graphlit.co/install.sh | sh — and confirm with graph --version. From 0.1.5 the command hashes your own checkout and exits 1 on drift. The detail.

`graph drift` says everything drifted

Usually one of two things:

  • The graph is old. A drift report against a .vipl/graph.json from weeks ago is a report about a system you no longer have. Import or sync first.
  • The deployment has not caught up. The files being hashed are the deployment's copy, not your working tree — see Keeping the graph true. Local edits that have never been through a task are invisible to it, in both directions.

The health scan is noisy

Findings are hypotheses, and severity is the filter that matters: graph check fails on errors only, and passes warnings and notes on purpose. A finding you have already judged keeps its fingerprint across runs, so what is new is genuinely new.

`CERTIFICATE_VERIFY_FAILED`, especially on macOS

A compiled binary carries no certificate trust of its own. Every call tries the system store first and only falls back to a bundled root set once verification has actually failed — so seeing this means both were refused. Reproduce it anywhere with:

sh
SSL_CERT_FILE=/nonexistent SSL_CERT_DIR=/nonexistent graph whoami

If you are behind a corporate proxy that intercepts TLS, its root must be in the system store — that is the case the fallback deliberately cannot rescue.

`could not tell <deployment> that <task> is <status>`

The build ran; the report did not arrive. Your folder is correct and the board is behind. It is printed as a warning rather than a failure because a build must not depend on the dashboard being reachable. Re-running the command once the connection is back re-reports it.

A command exits `2`

Not a failure of the check — a failure to run it. The deployment was unreachable or the credential was refused. Treat it as a build failure in CI: a gate that could not run is not a gate that passed.

Still stuck

graph --json status and graph --json health are the two documents worth attaching to a question. Neither contains a credential. Tell us what happened and include which command, what you expected, and what it printed.