hydrate CLI

Command-line client for hydrate.sh — author your graph from the terminal.

What it is

hydrate is a thin client over the hydrate.sh /v1 API. The CLI stages edits locally and commits them as one typed delta batch under optimistic concurrency control; the server is the sole authority for validation. It does not mirror the server's rules; a bad batch is rejected by the server.

The binary is hydrate, with a short alias hyd.

Every command reads human-friendly on a terminal and emits machine-readable JSON when piped (or with --json), and read commands return the whole node — its description (which is its prompt), constraints, and verifications — so hydrate doubles as a scriptable surface for an agent that builds from the living spec. Use hydrate walk <path> to read one node's scoped context (the node plus its immediate neighborhood, or a boundary's children with --boundary) without pulling the entire graph.

Command surface

hydrate init                 Write a pointer to `hydrate guide` into this directory's AGENTS.md
hydrate projects             List the projects on your account (ids for --project)
hydrate project create <name>              Create a project on your account
hydrate project archive <name>             Archive a project (non-destructive)
hydrate project restore <name>             Reverse an archive
hydrate project rename <name> --to <new>   Rename a project
hydrate project delete <name>              Permanently delete a project — cannot be undone
hydrate fork <name>          Fork a working branch from main, bind this directory to it
hydrate branches             List your working branches
hydrate show [path] [--depth N]          Print a read-only view of a branch's graph
hydrate walk <path>          Read one node's scoped context (node + neighborhood)
hydrate pull                 Refresh the local view of the branch's graph
hydrate node add ...         Stage a node (behavior or boundary)
hydrate node set <path> ...  Stage an edit to a node (description, ports, ...)
hydrate node mv <path> ...   Stage a reparent of a node
hydrate node rm <path>...    Stage removal of nodes (cascades the subtree)
hydrate edge add ...         Stage an edge between two typed ports
hydrate edge rm ...          Stage removal of an edge
hydrate boundary flatten ... Promote a boundary's children and remove it
hydrate clear                Stage removal of every top-level node
hydrate status               Show the bound branch + staged-operation summary
hydrate diff                 Show staged operations in detail
hydrate validate             Dry-run the staged change; report coherence findings
hydrate commit               Commit the staged changeset to the bound branch

hydrate validate posts the staged changeset to the server for a dry-run — it never commits and never clears the stage — and prints the coherence findings. It exits 0 when there are no error-severity findings and a distinct nonzero code (5) when there are, so an agent can gate a loop:

hydrate validate && hydrate commit

Findings are reported against the dotted paths you author with (Api.Rater.key), not the server's internal ids, so you can act on one directly — and paste the path into the next command. With --json the payload is {valid, findings[], located[]}:

• findings[] is the server's report verbatim, ids intact, for correlating with the API.
• located[] is the same list resolved for use. Each entry carries finding_index (its position in findings[] — two findings can share a locator, so that is the join key), path, path_complete, and a message with the ids replaced.

Paths are resolved from this working copy, so run hydrate pull if it is behind the branch. When a path cannot be resolved the raw id is shown rather than guessed at, path is null, and a note explains why on stderr.

Run hydrate guide for an orientation, or see the full reference at docs.hydrate.sh.

Managing projects

hydrate project create|archive|restore|rename|delete address a project by its exact name (no id, no partial match) — and resolve against both active and archived projects, so an already-archived project's name still works.

archive is the non-destructive escape hatch: an archived project stops appearing in hydrate projects but is not gone, and hydrate project restore <name> reverses it — the round trip is real, not just a server-side capability this CLI can't reach. Renaming uses a flag for the new name (rename <name> --to <new-name>), not a second bare positional, so the current and new names can never be silently transposed into a rename in the wrong direction.

delete is permanent: it removes the project's branches, graph, and stored artifacts, and there is no confirmation prompt (this CLI is built to be driven non-interactively), so it prints what is about to go before it does the irreversible part.

delete requires an API key minted with the project:delete scope, which is separate from graph:write and not granted by it — a key that can author a graph cannot also erase one unless it was minted with this scope on purpose. If your key predates this scope (or was minted without asking for it), hydrate project delete reports exactly that instead of a bare 403 — unless the 403 is for an unrelated reason (e.g. a whitelist-scoped key whose per-key project allowlist excludes this project), in which case it reports that instead of guessing.

Choosing a project

Commands that act on a project resolve it in this order: the --project <name|id> flag, the HYD_PROJECT environment variable, this directory's binding, and finally — if you have exactly one active project — that project. With more than one project and no selection, the command stops and tells you how to disambiguate. Run hydrate projects to list the names and ids.

Authoring is flag-driven and explicit, so a command reads the same in a script as on the terminal:

hydrate node add --kind behavior --name Rater --in raw:HotDog --out score:Score
hydrate edge add --from Maker.dog --to Rater.raw
hydrate commit

A boundary can declare its target language — it flows to code generation and to the nodes nested under it. Set it with --language (on node add or node set), or drop it with node set --clear-language:

hydrate node add --kind boundary --name Core --language python
hydrate node set Core --clear-language

Install

Prebuilt binaries (no toolchain needed) ship with each tagged release. Download the archive for your platform from the Releases page, check it against its published .sha256, and put hydrate (and the hyd alias) on your PATH:

# Linux x86_64 — adjust the version and target for your platform.
tag=v0.1.11
target=x86_64-unknown-linux-gnu
curl -fsSLO "https://github.com/hydrate-sh/cli/releases/download/${tag}/hydrate-${tag}-${target}.tar.gz"
curl -fsSLO "https://github.com/hydrate-sh/cli/releases/download/${tag}/hydrate-${tag}-${target}.tar.gz.sha256"
sha256sum -c "hydrate-${tag}-${target}.tar.gz.sha256"
tar xzf "hydrate-${tag}-${target}.tar.gz"
./hydrate --version

Each release publishes archives for Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64), each with a .sha256 checksum. The archives also carry signed build provenance — verify it with gh attestation verify <archive> --repo hydrate-sh/cli.

Building from source

Requires the Rust toolchain pinned in rust-toolchain.toml.

cargo build
cargo test

Configuration

• HYD_API_KEY — your API key (read from the environment or a .env file).
• HYD_BASE_URL — override the service URL (for local development).
• HYD_PROJECT — the project (name or id) to act on when --project is not given and the directory is not bound. See Choosing a project.

License

MIT — see LICENSE.