Skip to main content
← For agents

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.

qURL CLI JSON fields, by question
QuestionCommandField
This device’s public keyqurl whoami -o jsondevice_public_key_b64
The CRID of what was publishedqurl publish <target> -o jsoncrid
Is it private?qurl publish, qurl grantsprivate, true only for a private resource
Was this address published before?qurl publishfound_existing
Is a local app serving now?qurl status <CRID> -o jsondesired_state and connection_state
Why is a local app not serving?qurl inspect <CRID> -o jsondaemon_state, failure_code, local_target_health
Which devices may open it?qurl grants <CRID> -o jsonallowed_device_keys
An access linkqurl share <CRID> -o jsonqurl, single_use, expires_at
What does this device own?qurl list --status active -o jsonresources, has_more, next_cursor
Did a delete go through?qurl delete <CRID> --yes -o jsonid 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.

Output: 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.

Output: 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/null

status: 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.

Output: 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 json

inspect: 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.

Output: 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.

Output: 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/null

share: a link for one visit

qurl is the link. It is not url or link, and it is a secret: keep the document out of logs and print the link only to the person or agent it is for. single_use is true for a one-time link and is left out when the link is reusable, so a missing single_use is not a one-time link. expires_at and expires_in_seconds say when the link stops opening.

share runs as the identity of the machine it runs on: the owner, or a device on the resource’s list. The link opens in a browser. Fetching it with curl returns the opener page, not the app.

Output: qurl share <CRID> --ttl 15m -o json
{
  "qurl": "https://qurl.link/#qv2t1.1.1.1.AQ.AQ.AQ",
  "crid": "qhtpthw4qt7wkw7khghr6x3z4hsfyn4zbuyhnee4i6bi67yu6yytgvwdbb4q",
  "type": "qv2",
  "expires_at": "2026-03-01T00:15:00Z",
  "expires_in_seconds": 900,
  "single_use": true,
  "resource_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.

link=$(qurl share "$CRID" --ttl 15m -o json | jq -er 'select(.single_use == true) | .qurl')

list: 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.

Output: 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.

Output: 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.

grants is not status, and neither is a browser test

grants says who may open a resource. status and inspect say whether it is being served. A local app’s status document has no private field at all, so a script that looks for private there finds nothing and must not read that as public or as private.

Neither one shows that a recipient can use the app. That takes the recipient’s own link, opened in the recipient’s own browser, as the page on verifying private access describes.

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.

Read the skill →

Book a pilot

Tell us what to hide. We’ll scope a pilot.

Enterprise starts with a paid pilot on one application, typically 60 to 90 days, credited in full toward year one if you convert within 60 days. After that, an annual package sized to what you protect, not per seat.