CLI & agent skill documentation

01 / Start

Install the CLI

Install globally, or prefix any command with npx -y trycase@latest to run without an install.

Install

npm install --global trycase
trycase login

No install

npx -y trycase@latest capabilities --pretty

A complete verification flow

trycase doctor --pretty
trycase repository show
trycase pr show owner/repository#123
trycase verify run owner/repository#123 --prompt-file verification.md
trycase verify follow <bot-id>
trycase result list <bot-id> --pretty
trycase artifact list <bot-id> --pretty

Uses your checkout

Leave out the repository and TryCase reads owner/name from the current Git remote.

Follow a run

Stream status changes as NDJSON and see when the bot needs your help.

Download results

List, view, and download screenshots and captioned videos.

02 / Authentication

Browser login for people. Environment credentials for automation.

trycase login uses device authorization and stores a 90-day grant with owner-only filesystem permissions. Use --no-open on a remote shell.

Interactive

trycase login --no-open
trycase whoami --pretty

CI / automation

export TRYCASE_API_URL=https://api.trycase.dev
export TRYCASE_TOKEN=<token>
trycase whoami --pretty

Tokens are never accepted as command-line arguments. Set TRYCASE_TOKEN and TRYCASE_API_URL together, and never print them in logs.

03 / Reference

Command reference

All examples begin with trycase. Add --pretty for readable JSON or --timeout 60 to change the HTTP timeout.

Account & discovery

Authenticate, inspect the local setup, and discover the live machine contract.

Command	Arguments	Purpose
login	[--no-open] [--api-url <url>]	Start browser device authorization.
logout	None	Revoke the current grant and remove stored credentials.
whoami	None	Return the authenticated account.
doctor	None	Check configuration, API origin, and authentication.
capabilities	None	Return the versioned command manifest.

Repositories & pull requests

Resolve connected GitHub targets. Repository arguments can be inferred from the checkout.

Command	Arguments	Purpose
repository list	[--limit <1-100>] [--cursor <cursor>]	List connected repositories.
repository show	[owner/repository]	Inspect a repository by ID, slug, or URL.
pr list	[owner/repository] [--limit <1-100>]	List pull requests for a repository.
pr show	<owner/repository#number>	Inspect one pull request.

Verification

Start, observe, continue, stop, and archive verification agents.

Command	Arguments	Purpose
verify run	<PR> [--prompt-file <path>] [--model <id>]	Start a verification; supports --request-id.
verify list	[repository] [--limit <1-100>]	List recent verification bots.
verify status	<bot-id>	Read the latest state without waiting.
verify wait	<bot-id> [--wait-timeout <seconds>]	Wait for terminal or attention state.
verify follow	<bot-id> [--wait-timeout <seconds>]	Stream changed states as NDJSON.
verify message	<bot-id> (--message <text> \| --message-file <path>)	Continue the same bot with a follow-up.
verify stop	<bot-id> --yes	Pause active work and preserve its history.
verify archive	<bot-id> --yes	Archive a completed or stopped bot.

Requested secrets

Provide selected local values for a bot's pending secret requests without exposing them in command arguments or output.

Command	Arguments	Purpose
secret list	<bot-id>	Inspect requested names and reasons; never returns secret values.
secret set	<bot-id> --name <NAME> [--host NAME=hostname] (--env-file <path> \| --from-environment) --yes	Upload approved requested names. Add a host for opaque keys used by an external service.

Results & proof

Inspect verdicts and retrieve screenshots or captioned demo videos.

Command	Arguments	Purpose
result list	<bot-id> [--limit <1-100>]	List saved findings and verdicts.
result show	<result-id>	Read one complete result.
artifact list	<bot-id> [--limit <1-100>]	List proof attached to a bot.
artifact url	<artifact-id>	Create a viewable signed URL.
artifact download	<artifact-id> --output <path> [--force]	Download proof to an explicit path.

04 / Workflow

Run a test from start to finish

Check for an existing bot, follow the run, and wait for a final result before reporting it as complete.

01
Check the CLI
Run capabilities and doctor to see the commands and confirm your connection.
02
Find the PR
Check the repository, pull request, and recent bots before starting a new one.
03
Start testing
Put longer instructions in a file and keep the request ID in case you need to retry.
04
Follow the run
Stream changes. The result is still provisional while terminal is false or messages are queued.
05
Handle requests
If the bot needs help, read attentionReason and actionUrl. Use secret list for missing credentials.
06
Share the result
Report the commit, final verdict, result IDs, and links to the saved screenshots and videos.

Idempotency: verify run and verify message accept --request-id. Reuse the same value after an ambiguous network failure to avoid duplicate work.

Secrets

Send a requested secret from your machine

If a test needs a credential, your coding agent can find it in a local dotenv file or environment and send it through the CLI.

Provide requested secrets

trycase secret list <bot-id> --pretty
# After the user approves the selected names and local sources:
trycase secret set <bot-id> --env-file .env.local --name DATABASE_URL --name API_KEY --host API_KEY=api.example.com --yes
# Or read a selected value already exported in the process environment:
trycase secret set <bot-id> --from-environment --name DATABASE_URL --yes
trycase verify follow <bot-id>

The agent should look only at development or test configuration in the current checkout. Before sending anything, it should show you the variable names and where it found them. It should never print the values, paste them into chat, or put them in command arguments.

--yes confirms the names you approved. Choose either --env-file or --from-environment, and repeat --name for each value. URL credentials and common provider keys get a host restriction automatically. For another external service, add --host NAME=hostname. TryCase accepts only requested secrets and never returns their values.

Inside the test machine, the app receives an opaque placeholder. TryCase reveals the real value only when the app connects to an allowed host. The value is never written into the repository workspace.

Then follow the same bot to see whether it needs anything else. Sending deployment credentials does not approve a deployment; that still happens in the web app.

05 / Output

JSON for commands, NDJSON for live updates

Normal commands write one versioned envelope to stdout. Errors write one envelope to stderr. verify follow emits changed-state events followed by a final result envelope.

Success envelope

{
  "schemaVersion": 1,
  "ok": true,
  "command": "verify status",
  "data": {
    "botId": "...",
    "status": "running",
    "terminal": false,
    "requiresAttention": false
  }
}

Error envelope

{
  "schemaVersion": 1,
  "ok": false,
  "command": "verify status",
  "error": {
    "code": "NOT_FOUND",
    "message": "Verification not found",
    "httpStatus": 404
  }
}

terminal

true only when the current queue has finished or the bot is archived.

requiresAttention

signals that a person must complete the returned action.

nextCursor

is opaque; pass it back unchanged when requesting the next page.

06 / Agent skill

Teach your coding agent to use TryCase

The TryCase skill shows coding agents how to sign in, find pull requests, avoid duplicate runs, follow tests, and return the final results.

SKILL.md

trycase-cli

A Markdown skill with the commands, safety checks, and steps an agent needs to run TryCase.

View raw skill ↗

Install in this repository

mkdir -p .agents/skills/trycase-cli
curl -fsSL https://www.trycase.dev/skills/trycase-cli/SKILL.md \
  -o .agents/skills/trycase-cli/SKILL.md

.agents/skills works as a project-level location for many coding agents. Check your agent’s docs if it looks for skills elsewhere.

07 / Safety

Safety checks built into the CLI

Confirm stop and archive

Stopping and archiving require --yes. Check the bot ID before changing its state.

Do not overwrite by accident

Downloads need an output path and refuse to replace an existing file unless you pass --force.

Limit file input

Prompt and message files must be regular, non-symlink files no larger than 32 KiB. Use - for stdin.

Reject unsafe URLs

The CLI rejects redirects and URLs containing usernames or passwords. Signed artifact URLs are supported.

08 / Errors

Stable exit codes for automation

Branch on the process exit code, then parse the JSON error envelope for the stable code, redacted message, and optional HTTP status.

Exit	Meaning
0	Success
2	Invalid command or input
3	Missing or invalid configuration
4	Authentication or authorization failure
5	Resource not found
6	Conflict
7	TryCase API failure
8	Network error or wait timeout
9	Local filesystem error

Try it

Connect a repository and run TryCase from your terminal.

Connect repository Get the skill

Run TryCase from your terminal. Give your agent the same tools.