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.
Before you start
Section titled “Before you start”- 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,toolsand every read tool. Anything that writes needs Read and write, whether you sign in or use a key. - Node 20.12 or later.
node --versiontells you. - The right package name. Bare
npx hydrantruns someone else’s package. Always ask for@hydrantdev/cli.
Sign in
Section titled “Sign in”npm i -g @hydrantdev/cliinstalls thehydrantcommand. The examples below use that name;npx @hydrantdev/cliworks anywherehydrantdoes.- 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. - The tab says You’re signed in. Back in the terminal,
hydrant whoamishows 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 loginagain with another workspace adds it and makes it the default.hydrant workspacelists your sign-ins and marks the default;hydrant workspace acmeswitches.--workspace acmeuses another sign-in for one command.hydrant logoutrevokes the connection and forgets the sign-in;--alldoes 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.
Or use an agent key
Section titled “Or use an agent key”- Put the key in the environment.
read -s HYDRANT_KEY(paste, then Return) keeps it out of your shell history; thenexport HYDRANT_KEY. - 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.
Read issues
Section titled “Read issues”hydrant list # open issues, newest firsthydrant list --status "in progress" --assignee adahydrant list --assignee ada --with-agents # Ada plus the agents she ownshydrant list --view all --all --q export # include Done and Canceledhydrant view 12 # one issue and its latest activityNames 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.
Daily commands
Section titled “Daily commands”hydrant create "Fix the export copy" --label bug --priority highhydrant edit 12 --label copy --remove-label bughydrant status 12 "in progress"hydrant assign 12 "Claude · Henry Kobutra" # or nonehydrant comment 12 "Fixed in the export PR"hydrant open 12On 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.
createandedittake--title(editonly),--description,--priority,--size,--label,--projectand--milestone;createalso takes--status,--assigneeand--parent.--labeladds to the issue’s labels and--remove-labeltakes one away; the rest stay.--editopens your editor ($VISUAL, then$EDITOR) on the description or a new comment. To pipe text in a script, use--description -orhydrant 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
--editstays in a file the error names); reread withhydrant viewand try again. - Ready needs a refined issue.
hydrant status 12 readyon one that isn’t says so and changes nothing.
Call any tool
Section titled “Call any tool”hydrant tools get_issue # one tool's input schemahydrant call get_workspace_identityhydrant 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.
Script it
Section titled “Script it”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.
Export an issue’s work record
Section titled “Export an issue’s work record”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:
hydrant call read_work_record '{"issueId":"00000000-0000-4000-8000-000000000000"}' | jq '.data' > record.jsonThe 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.
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"}}'Sign and verify a work record
Section titled “Sign and verify a work record”Call sign_work_record to get the same record signed, so anyone can check later that nobody changed it:
hydrant call sign_work_record '{"issueId":"00000000-0000-4000-8000-000000000000"}' | jq '.data' > record.dsse.jsonThe 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.jsonimport { 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.
Tab completion
Section titled “Tab completion”source <(hydrant completion zsh) # zsh: in ~/.zshrc, after compiniteval "$(hydrant completion bash)" # bash: in ~/.bashrchydrant completion fish > ~/.config/fish/completions/hydrant.fishTab 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.
What you should see
Section titled “What you should see”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 copyIf 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 copyhttps://hydrant.dev/acme-k3xrq2m7pa/issues/646#646 → In Progress#646: labels +bug −copyCommented on #646call 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-1c1a79dfe093hydrant whoami prints who the next command acts as:
https://hydrant.devWorkspace Acme (member)Access read and writeUsing signed-in profile · Hydrant CLI (ada-laptop)Expires 2026-11-10hydrant 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/cliIt 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.
If it goes sideways
Section titled “If it goes sideways”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_URLtakes an origin only:https://hydrant.dev, with no path, no query and no trailing/api/mcp. Plainhttpworks 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 loginand 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 useHYDRANT_KEY. - Login gave up after 5 minutes. Nothing was saved. Run
hydrant loginagain and approve in the tab it opens, or copy the URL it prints. hydrant logoutsays 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
listacross pages, can wait more than once. - Exit 6 after a write. The write may have gone through. Retry with the
--request-idfrom 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.