Command reference

Global flags

Most commands also take --api URL. Leave it off and the deployment is worked out for you: the flag, then VIPL_API, then the folder's link file, then the account you are signed in to, then the built-in default.

Accounts

graph login

graph login [-h] [--api API] [--no-browser] [--api-key [API_KEY]]

Sign this machine in to a deployment through the browser device flow, or with an API key.

graph logout

graph logout [-h] [--api API]

Forget the stored credential for a deployment. Local only — it makes no network call and does not end the session in your browser.

graph whoami

graph whoami [-h]          # machine-readable: graph --json whoami

Which account this machine is signed in as, for every deployment it holds. Reads the local store only, on purpose: the question it answers is why is everything 401?, and that is exactly when the network is the problem.

graph setup

graph setup [-h] [--api API] [--app APP] [--no-browser] [--path PATH]

Sign in and bind a folder to a project, in one command — what the installer runs on its last line. Each step is recorded rather than raised, so a later failure never erases an earlier success, and --json gives the whole sequence as data.

Projects and folders

graph projects

graph projects [-h] [--api API]

Every project this account can open, with the id graph link --project takes — the same id the board puts in its URL.

graph link

graph link [-h] [--api API] [--project PROJECT] [--path PATH]

Attach a folder to a project, writing .vipl/link.json. With no --project and a terminal to ask in, it lists your projects and lets you pick a number.

graph status

graph status [-h] [--api API] [--path PATH] [--all] [project]

Is this folder connected, and how far has the plan got? Names the deployment, the account, whether a terminal is attached and where, and the task count. PROJECT accepts the id or the name you read on screen.

Verification

All three take the same arguments: an optional project (id or the name shown on the board), --path and --api. In a linked folder they need none of them.

All three read .vipl/graph.json out of the folder and send it. graph drift, and the drift half of graph check, then hash the mapped files in your checkout and send that census too — so they answer about the tree in front of you. graph health scans the deployment's copy of the project. Run them in a checkout that has the graph — from an empty directory there is nothing to send and they stop. What that means in practice.

graph drift

graph drift [-h] [--api API] [--path PATH] [project]

Hash-verify the graph against the code. Exits 1 when anything has drifted and 0 when nothing has, which is what makes it usable as a pipeline gate. Each drifted node is listed with its status — modified, missing, unbuilt — and the files behind it.

graph health

graph health [-h] [--api API] [--path PATH] [project]

The deterministic defect scan: nine finding kinds, each with a severity. Hypotheses, not confirmed defects — see Keeping the graph true.

graph check

graph check [-h] [--api API] [--path PATH] [project]

The CI gate: health errors and drift together, one exit code. Passes on warnings and notes.

Building

graph agent

graph agent [-h] [--api API] [--path PATH] [--all] [--project PROJECT]

Connect this terminal so that Execute on the board builds here. Outbound-only — nothing listens, no port is opened. Runs until Ctrl-C.

A folder holds one runner at a time; a second in the same folder refuses rather than starting.

graph run

graph run [-h] [--api API] [--path PATH] [--project PROJECT] [--next]
          [--all] [--force] [--agent AGENT] [--timeout TIMEOUT]
          [--push] [--no-push] [task]

Build one task here, now, with no board involved — same goal, same scope enforcement, same commit, same report as Execute.

`graph run --all` finishes the plan without a browser. It re-reads the plan after every task, so a task that was blocked at the start becomes the next one the moment its dependency passes; it stops at the first failure, because the tasks after it are scoped against files the failed one was supposed to write; and running it again resumes from where it stopped.

graph run --all               # the rest of the plan, in order
graph run --all --push        # ...and push each task that passes

graph undo

graph undo [--yes] [--project ID] [--path DIR] [--api URL]

Revert the last build commit and put its task back to pending, so the plan is runnable again. Shows what it is about to do and asks first; --yes skips the question.

graph tasks

graph tasks [PROJECT] [--remote] [--path DIR] [--api URL] [--json]

The build plan for this folder. Reads .vipl/tasks.json and makes no network call when it is there; --remote asks the deployment instead.

Settings

graph config

graph config                 every setting, its value, and its source
graph config KEY             just that one
graph config KEY VALUE       set it
graph config --unset KEY     back to the default

The source column is the feature: a value that is set here and overridden by an environment variable looks, from every other command, like configuration being ignored.

graph help

graph help [topic]

Everything the client can do on one screen, grouped by what you are trying to get done rather than alphabetically — which is what --help gives you, and --help is unchanged. It also lists the environment variables, which --help cannot show at all.

graph help <command> is that command's own --help, so there is one description per command rather than a second manual to keep current.

graph, on its own

graph with nothing after it is a signpost, not a command list: which account you are on, whether this folder is attached to a project, and the one next thing to type. It reads locally only, so it answers instantly and still works when the deployment does not.