Skip to content

Use the Hydrant CLI

The Hydrant CLI calls the same tools your agent does, from a terminal or a CI job. Use it to read the board without opening a browser, or to have a pipeline move an issue when the work it describes lands. It’s the @hydrantdev/cli (opens in a new tab) package on npm, with no dependencies. It stores sign-ins, never pasted keys.

  • A browser where you’re signed in to Hydrant, for hydrant login. On a server or in CI, use an agent key instead: create one under Settings › Agents › Access; Agent keys covers the details.
  • Read only access runs list, view, tools and every read tool. Anything that writes needs Read and write, whether you sign in or use a key.
  • Node 20.12 or later. node --version tells you.
  • The right package name. Bare npx hydrant runs someone else’s package. Always ask for @hydrantdev/cli.
  1. npm i -g @hydrantdev/cli installs the hydrant command. The examples below use that name; npx @hydrantdev/cli works anywhere hydrant does.
  2. Run hydrant login. Your browser opens Hydrant’s Connect page, the same one agents use. Pick the workspace and Read only or Read and write, then approve.
  3. The tab says You’re signed in. Back in the terminal, hydrant whoami shows the workspace, your access and when the sign-in expires.

The CLI keeps the sign-in in the macOS Keychain, or the Secret Service on Linux when secret-tool is installed. Anywhere else it’s in credentials.json in ~/.config/hydrant, readable only by you, and login says so. It refreshes on its own; a sign-in you don’t use for 30 days expires.

The sign-in shows up under Settings › Agents › Access as Hydrant CLI (your computer’s name). Each workspace you sign in to is its own connection and counts toward your plan’s connections, like any agent. Signing in to the same workspace again revokes the old one. On the Free plan, run hydrant logout first if the workspace is at its limit.

  • hydrant login again with another workspace adds it and makes it the default.
  • hydrant workspace lists your sign-ins and marks the default; hydrant workspace acme switches.
  • --workspace acme uses another sign-in for one command.
  • hydrant logout revokes the connection and forgets the sign-in; --all does every workspace.

--no-browser prints the sign-in URL instead of opening it. Over SSH or on a headless machine, the browser can’t reach the CLI to finish signing in, so use an agent key there.

  1. Put the key in the environment. read -s HYDRANT_KEY (paste, then Return) keeps it out of your shell history; then export HYDRANT_KEY.
  2. Run hydrant tools. That lists every tool the key can call, one line each.

A key always wins: --key, then HYDRANT_KEY (or HYDRANT_AGENT_KEY), then --workspace, then your default sign-in. So a CI job with a key never picks up a sign-in. HYDRANT_URL defaults to https://hydrant.dev. --key and --url override the environment for one run.

Terminal window
hydrant list # open issues, newest first
hydrant list --status "in progress" --assignee ada
hydrant list --assignee ada --with-agents # Ada plus the agents she owns
hydrant list --view all --all --q export # include Done and Canceled
hydrant view 12 # one issue and its latest activity

Names match case-insensitively, or by a unique start like --project cli. --with-agents needs --assignee naming a person and adds every named agent that person personally owns, the same set as Cockpit; shared agents stay out. An unknown status, person, label, project or milestone suggests the nearest one or lists the valid ones instead of guessing.

Terminal window
hydrant create "Fix the export copy" --label bug --priority high
hydrant edit 12 --label copy --remove-label bug
hydrant status 12 "in progress"
hydrant assign 12 "Claude · Henry Kobutra" # or none
hydrant comment 12 "Fixed in the export PR"
hydrant open 12

On a branch named for an issue, like henry/hyd-12-fix-export, leave the number out: hydrant status done moves #12 and says Using #12 from branch henry/hyd-12-fix-export first. An issue can also be HYD-12, your workspace’s own key, or its ID.

  • create and edit take --title (edit only), --description, --priority, --size, --label, --project and --milestone; create also takes --status, --assignee and --parent. --label adds to the issue’s labels and --remove-label takes one away; the rest stay.
  • --edit opens your editor ($VISUAL, then $EDITOR) on the description or a new comment. To pipe text in a script, use --description - or hydrant comment 12 -.
  • When two agents share a name, use the full name Hydrant shows, like Claude · Henry Kobutra. Retired agents can’t take new work.
  • If someone saves the issue while you’re editing, a status, assignee, priority, size, label or project change tries once more. A title or description change stops instead, so their words and yours both survive (text from --edit stays in a file the error names); reread with hydrant view and try again.
  • Ready needs a refined issue. hydrant status 12 ready on one that isn’t says so and changes nothing.
Terminal window
hydrant tools get_issue # one tool's input schema
hydrant call get_workspace_identity
hydrant call list_issues '{"limit":5}'
echo '{"limit":5}' | hydrant call list_issues -
hydrant call count_issues '{"filters":{"view":"open"},"facet":"assignee"}'

Arguments are one JSON object. Only - reads them from stdin, so a script with an open pipe never hangs waiting.

Write tools need a request id. Leave it out and the CLI makes one and prints it to stderr. If a write fails partway, retry with --request-id and that id, and it lands once. Writes that don’t bite explains why.

list, view, call and the daily commands print compact JSON when piped or with --json; tools needs --json. hydrant list --json | jq '.issues[].title' does what it looks like.

In GitHub Actions, keep the key in a repository secret. This step moves an issue to Done; update_issue needs the issue’s current version, so it reads that first:

- name: Mark the Hydrant issue done
env:
HYDRANT_KEY: ${{ secrets.HYDRANT_KEY }}
ISSUE_ID: 00000000-0000-4000-8000-000000000000 # the issue's id
run: |
version=$(npx --yes @hydrantdev/cli call get_issue "{\"issueId\":\"$ISSUE_ID\"}" | jq '.data.issue.version')
npx --yes @hydrantdev/cli call update_issue "{\"issueId\":\"$ISSUE_ID\",\"version\":$version,\"patch\":{\"status\":\"done\"}}"

Pin a version, like @hydrantdev/cli@0.3.0, if you’d rather upgrade on purpose.

An issue’s Agent Work Record says which agents worked on it, what they were allowed to do, the evidence they added and who signed off. Any key can read it, read-only keys included:

Terminal window
hydrant call read_work_record '{"issueId":"00000000-0000-4000-8000-000000000000"}' | jq '.data' > record.json

The record is the JSON under data. It lists agents by name and id only, never keys or email addresses.

A CI job can add a run to that record with add_work_record_evidence_fragment. It sends one evidence item as the key’s own agent; read_work_record gives the workspace and work.id to use, and by is that workspace plus /agents/ and caller.id from get_workspace_identity. The key needs write access. A retry with the same --request-id adds the run once.

Terminal window
hydrant call add_work_record_evidence_fragment '{"issueId":"…","spec":"agent-work-record/v0","workspace":"…","work":"…","evidence":{"id":"https://github.com/acme/app/actions/runs/123","kind":"ci_run","uri":"https://github.com/acme/app/actions/runs/123","claim":"ready_for_review","by":"…","at":"2026-10-16T12:00:00Z","result":"pass"}}'

Call sign_work_record to get the same record signed, so anyone can check later that nobody changed it:

Terminal window
hydrant call sign_work_record '{"issueId":"00000000-0000-4000-8000-000000000000"}' | jq '.data' > record.dsse.json

The file is a DSSE envelope (opens in a new tab). Its payload is an in-toto Statement v1 (opens in a new tab) in base64: the record is its predicate, and its subject is the merged commit of each pull request linked as closing the issue, or the record’s own sha256 when nothing has merged. That sha256 is over the record as compact JSON exactly as JavaScript’s JSON.stringify writes it (no spaces, no escaping beyond JSON’s own), so JSON.stringify(statement.predicate) gives the same bytes. Hydrant signs it with Ed25519 and publishes the public key, with its keyid, at /.well-known/agent-work-record/keys.json. Nothing is stored: each export is signed when you ask.

To verify it, check the signature over the DSSE pre-authentication encoding with the published key. This Node script (Node 20 or later, no packages) prints the record when it checks out:

// verify.mjs: node verify.mjs record.dsse.json
import { readFileSync } from 'node:fs'
import { createPublicKey, verify } from 'node:crypto'
const envelope = JSON.parse(readFileSync(process.argv[2], 'utf8'))
const { keys } = await (await fetch('https://hydrant.dev/.well-known/agent-work-record/keys.json')).json()
const { keyid, sig } = envelope.signatures[0]
const key = keys.find(k => k.keyid === keyid)
if (!key) throw new Error(`No published key with keyid ${keyid}`)
const body = Buffer.from(envelope.payload, 'base64')
const type = Buffer.from(envelope.payloadType)
// DSSE v1: "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body, lengths in bytes.
const pae = Buffer.concat([Buffer.from(`DSSEv1 ${type.length} `), type, Buffer.from(` ${body.length} `), body])
if (!verify(null, pae, createPublicKey(key.public_key_pem), Buffer.from(sig, 'base64'))) throw new Error('Signature does not verify')
const statement = JSON.parse(body)
console.log(JSON.stringify({ subject: statement.subject, record: statement.predicate }, null, 2))

Change one byte of the payload and the script stops with “Signature does not verify”. The keyid is the sha256 of the raw public key (public_key, base64), so you can also pin the key you trust instead of fetching it each time.

If an export with signed answers “Signing is not configured on this Hydrant server”, that server has no signing key yet. The plain export still works.

Terminal window
source <(hydrant completion zsh) # zsh: in ~/.zshrc, after compinit
eval "$(hydrant completion bash)" # bash: in ~/.bashrc
hydrant completion fish > ~/.config/fish/completions/hydrant.fish

Tab then completes commands, flags, statuses, assignees, labels, projects, sizes and tool names from your workspace. Two agents called Claude complete as Claude · Henry Kobutra and Claude · Arus, and a project name with a comma comes back escaped. Milestones complete once --project is on the line, and --workspace and hydrant workspace complete your signed-in workspaces. With no key, no sign-in or no network, Tab offers nothing and says nothing.

hydrant list in a terminal prints a table, in colour unless NO_COLOR is set:

# Status Priority Assignee Title
#12 In Progress High Ada Lovelace Rename the export button
#3 Backlog Urgent — Fix the login copy

If your filters can’t all hold, Hydrant leaves out what can’t hold and says why. The table prints each reason on stderr, one line each, and --json keeps them in conflicts.

hydrant view 12 prints the issue’s fields, its description and the five latest activity entries. The description is formatted for the terminal and wrapped to its width: headings, lists, task boxes, code, links and tables that fit. A blocked issue lists what blocks it.

Each daily command prints one line in a terminal:

Created #646 Fix the export copy
https://hydrant.dev/acme-k3xrq2m7pa/issues/646
#646 → In Progress
#646: labels +bug −copy
Commented on #646

call prints what the tool returned. Piped, it’s one line of JSON; in a terminal, indented. The tool’s answer sits under data:

{"workspace":{"id":"…","name":"Acme","role":"member"},"kind":"receipt","data":{"issue":{"number":12,"status":"done","version":3}}}

A write without --request-id also prints one line to stderr, which you keep in case you need to retry:

request id: 980d643b-1d14-4ff4-8f77-1c1a79dfe093

hydrant whoami prints who the next command acts as:

https://hydrant.dev
Workspace Acme (member)
Access read and write
Using signed-in profile · Hydrant CLI (ada-laptop)
Expires 2026-11-10

hydrant alone prints the overview. hydrant <command> --help gives an example for every flag that command takes.

Once a day the CLI checks npm for a newer version while your command runs, without slowing it down. If there is one, a single line follows a successful command on stderr:

Hydrant CLI 0.3.0 is out (you have 0.2.0). Update: npm i -g @hydrantdev/cli

It only shows when stderr is a terminal, and never with --json, when CI is set, or offline. Set HYDRANT_NO_UPDATE_NOTIFIER=1 (or NO_UPDATE_NOTIFIER=1) to turn it off.

Every failure prints one line to stderr: what happened, then what to do. Nothing goes to stdout. Piped or with --json, that line is a JSON object with code, message and hint. The exit code says which kind of failure it was:

Code Means The hint says
0 It worked.
1 The tool refused: not found, invalid arguments, not allowed for your role, too large, or Ready before refinement. What to fix, such as checking the arguments against hydrant tools <name>.
2 Usage: unknown command, flag or name, invalid JSON, not signed in and no key, or no issue in the branch. Run hydrant <command> --help, run hydrant login, or set HYDRANT_KEY.
3 Key or sign-in refused, read-only access on a write, origin refused, access lost, or you said no in the browser. Check the key, sign in again with read and write, or fix HYDRANT_URL.
4 Conflict: someone changed it first. Reread it and send the current version.
5 Rate limited, after one automatic retry. Try again in the number of seconds it gives.
6 Hydrant is unavailable or unreachable. Try again. For a write, reuse its --request-id.
  • Exit 2 and “must be an origin”. HYDRANT_URL takes an origin only: https://hydrant.dev, with no path, no query and no trailing /api/mcp. Plain http works only for a local server.
  • Exit 3 and “HYDRANT_URL must be the exact origin the key was issued for.” The shape is fine but Hydrant refused it: use the exact origin the key came from, usually https://hydrant.dev.
  • Exit 3 on a write with a read-only key. Create a Read and write key under Settings › Agents › Access and revoke the old one if nothing else uses it. Signed in read only? Run hydrant login and choose Read and write; the old sign-in is revoked for you.
  • Exit 3 and “Signed out of Acme.” The sign-in expired or was revoked in Settings. Run hydrant login.
  • “The keychain is locked.” Unlock it (log in to the Mac, or security unlock-keychain), or use HYDRANT_KEY.
  • Login gave up after 5 minutes. Nothing was saved. Run hydrant login again and approve in the tab it opens, or copy the URL it prints.
  • hydrant logout says the connection is still listed. Hydrant didn’t answer, so only this computer forgot the sign-in. Revoke Hydrant CLI (…) under Settings › Agents › Access.
  • Exit 5. A rate-limited request never runs, so the CLI waits and sends it once more when the wait is 30 seconds or less. If that fails too, or the wait is longer, it stops and tells you how long to wait. A command that makes several requests, like list across pages, can wait more than once.
  • Exit 6 after a write. The write may have gone through. Retry with the --request-id from stderr; Hydrant applies it once either way.
  • The key leaked. Keys live in Settings › Agents › Access, nowhere else. Revoke it there, now. The CLI never writes a key to disk, but your shell history or CI logs might have it.
  • Something else. When an agent gets stuck covers the errors the CLI passes through from Hydrant.