TestGator, from
your agent's shell.
testgator-cli is a command-line client for TestGator, built so an AI agent (Claude, or whatever you point at your terminal) can list projects, manage releases and test plans, invite testers, and review answers — without ever having to speak raw JSON-LD to the API itself.
- Pure REST client
- No MCP server needed
- No backend changes
$ testgator-cli login --username alice --password ••••••••
Logged in.
$ testgator-cli plan list --release 5
[{"id":12,"name":"Sprint 42 regression","state":"published"}]
$ testgator-cli test-invite bob@example.com --plan 12
{"success":true,"enrolled":true}
$ ▌
Why it exists
Agents shouldn't have to learn Hydra.
TestGator's API is proper JSON-LD/Hydra — great for a generic hypermedia client, expensive for an LLM reading it turn after turn. So testgator-cli sits in between: same public API testgator_client already talks to, zero new endpoints, just a much friendlier way in.
Envelope tax
Every response comes wrapped in @context, @id, @type, and hydra pagination links — metadata an agent pays token-rent on but never actually needs.
One idea, five round trips
"Duplicate this test plan" is one sentence to a human and four raw API calls under the hood. Someone has to compose those — it shouldn't be the agent, guessing.
Learning by 400
Auth flow, required fields, valid state transitions — an agent hitting the raw API discovers all of it by trial, error, and the occasional cryptic validation message.
How it works
Four ideas, one small binary.
Log in once
Authenticate once, cache the JWT locally. Every other command reuses it — no re-login per call.
Plain JSON, not Hydra soup
@context/@id/@type stripped, collections flattened. One compact line of JSON in, one line out.
Composed, not raw
Duplicating a plan or inviting + enrolling a tester is one command — the multi-call orchestration lives in the CLI, not in the agent's plan.
It documents itself
`testgator-cli guide` prints an agent-oriented cheat sheet — no filesystem access to this repo required.
Basic usage
From install to first answer.
One npm install, then you're talking to your TestGator instance in under a minute.
1. Install
npm install -g testgator-cli testgator-cli --help
Published on npm. Working against an unreleased change instead? Build from source — clone it, npm install && npm run build, then npm link.
2. Point it at your instance & log in
export TESTGATOR_API_URL=https://testgator.example.com testgator-cli login --username alice --password secret # or, interactively, first run: testgator-cli setup
3. Look around
testgator-cli project list testgator-cli release list --project 1 testgator-cli plan list --release 5
4. Do something
testgator-cli test-invite alice@example.com --plan 12 testgator-cli answer list --plan 12 --state failed testgator-cli answer edit 501 --comment "Reproduces every time."
Lost? Every command has a worked example baked into its own --help, and testgator-cli guide prints a full agent-oriented orientation — auth flow, output convention, the whole command list — in one shot. It's the first thing worth pointing an agent at.
Command reference
Every command, at a glance.
Every list command is paginated (--page, --items-per-page, defaulting to 20) and prints one compact line of JSON — an array for lists, an object for everything else, an Error: ... line on stderr with a non-zero exit code when something goes wrong.
| Command | Example |
|---|---|
| login / setup | testgator-cli login --username alice --password secret |
| project list / get | testgator-cli project list |
| release list / get / create / edit | testgator-cli release list --project 1 |
| plan list / get / create / edit / duplicate | testgator-cli plan create --release 5 --name "Regression" --due-date 2026-08-01T00:00:00+00:00 |
| question list / get / create / edit | testgator-cli question create --plan 12 --name "Can you log in?" |
| tester list / get | testgator-cli tester list --project 1 |
| answer list / get / edit / delete | testgator-cli answer list --plan 12 --state failed |
| invite / test-invite (+ batch) | testgator-cli test-invite alice@example.com --plan 12 |
| webhook enable / disable / set-url | testgator-cli webhook enable |
| guide | testgator-cli guide |
No answer create — answers come from testers via the mobile/web client, not this CLI. Full flag-level detail lives in each command's own --help.
Give your agent the keys.
It's a small, tested, self-contained tool — clone it alongside whatever TestGator instance you're already running.