qURL CLI JSON reference for automation
Which qURL JSON fields should an agent parse to publish, inspect, share, and delete a resource?
Add -o json to any qURL™ CLI command and read stdout; errors go to stderr, so check the exit code first. Read device_public_key_b64 from whoami, crid and private from publish, connection_state from status, allowed_device_keys from grants, qurl from share, resources and has_more from list, and id and deleted from delete. Pass the CRID, not resource_id, to every command.
Checked against the qURL CLI source of 3.6.1 and 3.7.1. Field names and types were read in the CLI source of 3.6.1 and 3.7.1 and its JSON test fixtures, and this site’s tests run every parser on the page against the document shown with it. The commands were not run against the service for this page. The two error texts come from the recorded runs behind the error reference. Verified .
How to read any qurl command
Add -o json and read stdout: it carries one JSON document, indented two spaces. Notes, warnings and errors go to stderr as text. Decide on the exit code first. A command that exits non-zero explains itself on stderr; don’t read its stdout as a result.
Optional fields are left out, never sent empty or null, so read them with jq -e: a missing field then stops the script instead of carrying null into the next command. A list the CLI always prints, such as allowed_device_keys, is an empty array when it holds nothing.
The field names below are the same in qurl 3.6.1 and 3.7.1, except that 3.7.1 can add terms_notice to the publish and share documents. Run qurl --version to see which release you have, and qurl <command> --help for what it accepts.
Which field answers which question
Read each answer from the command made for it. In particular, who may open a resource comes from qurl grants, and whether a local app is serving comes from qurl status.
| Question | Command | Field |
|---|---|---|
| This device’s public key | qurl whoami -o json | device_public_key_b64 |
| The CRID of what was published | qurl publish <target> -o json | crid |
| Is it private? | qurl publish, qurl grants | private, true only for a private resource |
| Was this address published before? | qurl publish | found_existing |
| Is a local app serving now? | qurl status <CRID> -o json | desired_state and connection_state |
| Why is a local app not serving? | qurl inspect <CRID> -o json | daemon_state, failure_code, local_target_health |
| Which devices may open it? | qurl grants <CRID> -o json | allowed_device_keys |
| An access link | qurl share <CRID> -o json | qurl, single_use, expires_at |
| What does this device own? | qurl list --status active -o json | resources, has_more, next_cursor |
| Did a delete go through? | qurl delete <CRID> --yes -o json | id and deleted, then a refused share |
whoami: the device public key
Run it on the machine that should be let in. device_public_key_b64 is the key the publisher adds with qurl grants <CRID> --add <KEY>. Send the public key through a channel that lets the publisher verify who sent it. Keep the private key in the state directory. On a new state directory, the first command creates the device identity and says “Using a new device identity.” on stderr.
Other names that look right, such as device_public_key or public_key, are not in the document.
qurl whoami -o json{
"owner_id": "<OWNER_ID>",
"auth_type": "<AUTH_TYPE>",
"device_public_key_b64": "cHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHA="
}Shape from the CLI’s whoami projection; owner_id and auth_type come from the service, and the key is a fixture value.
KEY=$(qurl whoami -o json | jq -er '.device_public_key_b64') ||
{ echo "no device public key" >&2; false; }publish: the CRID, and whether it is private
crid is what every later command takes. private is true only for a private resource: anything else, a missing field included, means it is not private, and the user must be told. A plain publish of a local app prints this document once the app is serving and exits. With --foreground it prints the document once serving starts and keeps running.
found_existing true means this device published the same address before: the resource keeps its CRID, its privacy and its allowed devices. Publishing it again with --allow-device-key cannot change that list; it fails with exit code 7 and “this target is already published, and its allowed devices differ from the ones this command named”. Change the list with qurl grants instead.
status here is the resource’s status on the service, such as active. It does not say that the app is being served: read qurl status for that.
qurl publish http://127.0.0.1:3000 -o json{
"private": true,
"access_requests": false,
"crid": "qhtpthw4qt7wkw7khghr6x3z4hsfyn4zbuyhnee4i6bi67yu6yytgvwdbb4q",
"resource_id": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE155W1ele0q0AK_YFZnQqzfhJLxqLgHaG3B5rXzPO87WZlnYa5TWlrbIO2C6ALvLxT7zaFWm9fc8PCklq1v4arg",
"target_url": "http://127.0.0.1:3000",
"status": "active",
"created_at": "2026-03-01T00:00:00Z",
"found_existing": false,
"publisher": {
"verified": false
}
}Shape from the CLI’s JSON projection in 3.6.1 and 3.7.1; the values are the synthetic ones of the CLI’s own test fixtures.
out=$(qurl publish "$TARGET" -o json) &&
CRID=$(printf '%s\n' "$out" | jq -er '.crid') &&
printf '%s\n' "$out" | jq -e '.private == true' >/dev/nullstatus: is the local app serving?
desired_state is what the owner asked for, on or off. connection_state is what the service sees: stopped, connecting or serving. The app is reachable through qURL only when both read on and serving. A CRID alone, or found_existing, proves neither.
This loop waits up to a minute, then prints the diagnostics if the app never got there. For a remote URL resource, status prints a different document, with type and status, because there is nothing to serve.
qurl status <CRID> -o json{
"crid": "qhtpthw4qt7wkw7khghr6x3z4hsfyn4zbuyhnee4i6bi67yu6yytgvwdbb4q",
"resource_id": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE155W1ele0q0AK_YFZnQqzfhJLxqLgHaG3B5rXzPO87WZlnYa5TWlrbIO2C6ALvLxT7zaFWm9fc8PCklq1v4arg",
"target_url": "http://127.0.0.1:3000",
"desired_state": "on",
"connection_state": "serving",
"serving_epoch": 1,
"created_at": "2026-03-01T00:00:00Z",
"publisher": {
"verified": false
}
}Shape from the CLI’s JSON projection in 3.6.1 and 3.7.1; the values are the synthetic ones of the CLI’s own test fixtures.
ready=""
for i in $(seq 1 30); do
if qurl status "$CRID" -o json |
jq -e '.desired_state == "on" and .connection_state == "serving"' >/dev/null; then
ready=yes; break
fi
sleep 2
done
[ -n "$ready" ] || qurl inspect "$CRID" -o jsoninspect: why it is not serving
inspect is status plus what this machine knows: daemon_state, local_target_health (healthy, unreachable, or not_available when this machine has no record of the share), and, when the daemon reports one, failure_category, failure_code, retry_attempt and next_retry_at. Run it with the same state as the publish: another identity or another machine has no local record to report.
The example is the share a failed publish leaves behind: desired off, stopped, with a healthy local app. Neither status nor inspect says who may open the resource.
qurl inspect <CRID> -o json{
"crid": "qhtpthw4qt7wkw7khghr6x3z4hsfyn4zbuyhnee4i6bi67yu6yytgvwdbb4q",
"resource_id": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE155W1ele0q0AK_YFZnQqzfhJLxqLgHaG3B5rXzPO87WZlnYa5TWlrbIO2C6ALvLxT7zaFWm9fc8PCklq1v4arg",
"target_url": "http://127.0.0.1:3000",
"desired_state": "off",
"connection_state": "stopped",
"serving_epoch": 1,
"created_at": "2026-03-01T00:00:00Z",
"publisher": {
"verified": false
},
"daemon_state": "stopped",
"last_transition": "2026-03-01T00:00:31Z",
"retry_attempt": 0,
"local_target_health": "healthy"
}Shape from the CLI’s JSON projection in 3.6.1 and 3.7.1; the values are the synthetic ones of the CLI’s own test fixtures.
qurl inspect "$CRID" -o json |
jq -r '"daemon: \(.daemon_state), app: \(.local_target_health), failure: \(.failure_code // "none")"'grants: who may open it
grants is the answer on authorization: private, allowed_device_keys (always an array), access_requests, and approved_people, the people approved through access requests. A missing approved_people means the service did not say, never that nobody was approved. qurl grants <CRID> --add <KEY> and --remove <KEY> print the same document after the change.
Check for the exact key you mean, not for a count. This exits 0 only when the resource is private and the key is on its list.
qurl grants <CRID> -o json{
"allowed_device_keys": [
"cHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHA="
],
"approved_people": [],
"access_requests": false,
"private": true,
"crid": "qhtpthw4qt7wkw7khghr6x3z4hsfyn4zbuyhnee4i6bi67yu6yytgvwdbb4q",
"resource_id": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE155W1ele0q0AK_YFZnQqzfhJLxqLgHaG3B5rXzPO87WZlnYa5TWlrbIO2C6ALvLxT7zaFWm9fc8PCklq1v4arg",
"target_url": "http://127.0.0.1:3000",
"type": "tunnel",
"status": "active",
"created_at": "2026-03-01T00:00:00Z",
"publisher": {
"verified": false
}
}Shape from the CLI’s JSON projection in 3.6.1 and 3.7.1; the values are the synthetic ones of the CLI’s own test fixtures.
qurl grants "$CRID" -o json |
jq -e --arg k "$KEY" '.private == true and any(.allowed_device_keys[]; . == $k)' >/dev/nulllist: everything this device owns, page by page
resources holds one row per resource, with crid, target_url, type, desired_state and private. has_more is always present and is the only end marker: an empty page with has_more true is normal, so keep following next_cursor. Pass --status active, or deleted resources come back too.
For a local app, target_url comes from this machine’s qurl state, so it can be missing when the list runs elsewhere. This loop prints the CRIDs published for one address and says when it could not read the whole inventory.
qurl list --status active -o json (the last page){
"resources": [
{
"allowed_device_keys": [
"cHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHA="
],
"private": true,
"crid": "qhtpthw4qt7wkw7khghr6x3z4hsfyn4zbuyhnee4i6bi67yu6yytgvwdbb4q",
"resource_id": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE155W1ele0q0AK_YFZnQqzfhJLxqLgHaG3B5rXzPO87WZlnYa5TWlrbIO2C6ALvLxT7zaFWm9fc8PCklq1v4arg",
"target_url": "http://127.0.0.1:3000",
"type": "tunnel",
"status": "active",
"desired_state": "off",
"serving_epoch": 1,
"created_at": "2026-03-01T00:00:00Z",
"publisher": {
"verified": false
}
}
],
"has_more": false
}Shape from the CLI’s JSON projection in 3.6.1 and 3.7.1; the values are the synthetic ones of the CLI’s own test fixtures.
cursor="" listed=""
while page=$(qurl list --status active -o json ${cursor:+--cursor "$cursor"}); do
more=$(printf '%s\n' "$page" | jq -r 'select((.resources | type) == "array") | .has_more | booleans') || break
case "$more" in true|false) ;; *) break ;; esac
printf '%s\n' "$page" | jq -r --arg t "$TARGET" '.resources[] | select(.target_url == $t) | .crid' || break
if [ "$more" = false ]; then listed=complete; break; fi
next=$(printf '%s\n' "$page" | jq -er '.next_cursor | strings | select(length > 0)') || break
[ "$next" != "$cursor" ] || break
cursor=$next
done
[ "$listed" = complete ] || { echo "inventory incomplete: delete nothing yet" >&2; false; }delete: confirm it went through
id is the CRID that was deleted, and deleted is true. A second delete of the same CRID prints deleted: true again, so the document shows that the service accepted the request, not that this run removed anything. already_gone appears only when the service no longer knows the CRID; don’t depend on it.
Confirm with qurl share: once the resource is deleted it fails with exit code 5 and “Resource Revoked (HTTP 400)”. A timeout, a network error, another exit code, or “Resource Not Found (HTTP 404)” confirms nothing: not found can mean that the command ran as an identity that never owned the CRID.
qurl delete <CRID> --yes -o json{
"id": "qhtpthw4qt7wkw7khghr6x3z4hsfyn4zbuyhnee4i6bi67yu6yytgvwdbb4q",
"deleted": true
}Shape from the CLI’s JSON projection in 3.6.1 and 3.7.1; the values are the synthetic ones of the CLI’s own test fixtures.
(
err=$(mktemp) || exit 1
trap 'rm -f "$err"' EXIT
qurl delete "$CRID" --yes -o json | jq -e --arg c "$CRID" '.id == $c and .deleted == true' >/dev/null &&
{ code=0; qurl share "$CRID" --ttl 1m >/dev/null 2>"$err" || code=$?; [ "$code" -eq 5 ]; } &&
grep -q 'Resource Revoked (HTTP 400)' "$err" && echo "delete confirmed"
)CRID and resource_id
The CRID is the resource’s permanent, portable reference, 60 characters long. Every qurl command takes it, and it is what a script stores and a person receives. resource_id is the service’s own identifier for the record. The JSON documents carry it for diagnostics, and the text output leaves it out.
Keep both in a script’s record of what it created, and pass the CRID to the CLI. Don’t build an API path from either one unless the API reference names the identifier that route takes.
Errors, and a publish that half worked
Errors are text on stderr with a stable exit code. Act on the exit code first and the message second; the error reference lists every message with its code.
A publish that exits non-zero can still have created the resource: a failure while starting the daemon or waiting for it to serve leaves the resource switched off. No field in the CLI’s output says so, because the CLI has no partial-success document. Find out from qurl list with the same state, as the recovery page describes, before you publish again or delete anything.
Frequently Asked Questions
Why does jq print null for the device key?
The field is device_public_key_b64, in the document qurl whoami -o json prints. device_public_key, devicePublicKey and public_key do not exist. Read it with jq -er so a wrong name fails instead of printing null.
Is the link in qurl share output called url or link?
Neither. It is qurl. Read it with jq -er 'select(.single_use == true) | .qurl' to get it only when the link opens once.
Does qurl inspect show whether a resource is private?
No. For a local app, status and inspect describe serving: desired_state, connection_state and this machine’s daemon. Run qurl grants <CRID> -o json for private and allowed_device_keys.
Which identifier does qurl delete take?
The CRID. qurl delete <CRID> --yes -o json prints it back as id, with deleted: true. Keep resource_id for your records only.
Is there a field that says a failed publish created a resource?
No. The CLI prints an error on stderr and a non-zero exit code, and no JSON document. Run qurl list --status active -o json with the same state and look for the address you published.
Give your agent the qURL skill
One file teaches a coding agent to publish an app privately, let people and other agents in, and recover when the CLI stops it. No account, no API key.