Scripting wrktr

The CLI is headless first: everything an agent needs from the web app, with --json output, and no clone required. That makes wrktr easy to drive from CI, a sandboxed agent, or a script.

Sign in with a token

On your own machine, once:

wrktr token create --name ci-deploy | pbcopy   # you approve it in the browser; it prints only the token

Then wherever the CLI runs:

export WRKTR_TOKEN=wrktr_...
wrktr whoami

WRKTR_TOKEN signs the CLI in without login. wrktr token ls lists your tokens (never their values) and wrktr token revoke <id> stops one at once.

No clone needed

--project <org>/<name> acts on a project on wrktr instead of the clone you’re in. Name the branch too, with --branch or the command’s branch argument:

wrktr status --project acme/api --branch fix-login
wrktr ci show --project acme/api --branch fix-login --wait
wrktr land fix-login --project acme/api --when-ready

JSON and exit codes

With --json, stdout carries exactly one JSON value, the command’s result; progress goes to stderr. A failure prints {"error": {"tag": "...", "message": "..."}} on stderr. Exit code 0 means the command did what it was asked, 1 that it didn’t, including a refusal such as land on a branch that isn’t ready. Act on the exit code, not the wording.

# Wait for a branch's checks, then land it when it's ready.
wrktr ci show --project acme/api --branch fix-login --wait --json > ci.json \
  && wrktr land fix-login --project acme/api --when-ready --json

# The review's verdict: approve, changes or comment.
wrktr status --project acme/api --branch fix-login --json | jq -r '.review.verdict'

The API directly

Everything the CLI does goes through the API, with the same token as a bearer token:

API=https://api.wrktr.com/api

# Who the token acts for.
curl -s -H "Authorization: Bearer $WRKTR_TOKEN" "$API/me"

# A branch's checks.
curl -s -H "Authorization: Bearer $WRKTR_TOKEN" \
  "$API/orgs/acme/projects/api/ci?branch=fix-login"

# Land it once it's ready.
curl -s -X PUT -H "Authorization: Bearer $WRKTR_TOKEN" -H "Content-Type: application/json" \
  -d '{"branch": "fix-login", "autoLand": true}' \
  "$API/orgs/acme/projects/api/branches/state"

Errors come back as JSON with a _tag naming them, and the fields that say what’s wrong. Landing a branch that isn’t ready, for example, is a LandBlocked with its failing and running checks, open threads and who requested changes. See API authentication.