# qURL CLI JSON reference for automation

> The qURL CLI’s -o json fields for whoami, publish, status, grants, share, list and delete, with a jq parser for each and how to confirm a delete.

Source: https://layerv.ai/for-agents/qurl-cli-json-for-automation/

---

[← For agents](https://layerv.ai/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 November 8, 2026.

## 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__
| 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.

Output: `qurl whoami -o json`

```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`

```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`

```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`

```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`

```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`

```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)`

```json
{
  "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`

```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.

## Related Resources

[qURL CLI errors and exit codes →](https://layerv.ai/for-agents/qurl-cli-errors/) [Recover a failed qURL publish safely →](https://layerv.ai/for-agents/recover-failed-publish/) [Private localhost access for AI agents →](https://layerv.ai/for-agents/private-localhost-access-for-ai-agents/) [Verify private access for browser agents →](https://layerv.ai/for-agents/verify-private-preview-access/) [The qURL skill (scripting contract, §7) →](https://layerv.ai/skills/qurl/SKILL.md) [qURL CLI →](https://layerv.ai/cli/)

## 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 →](https://layerv.ai/skills/qurl/SKILL.md)



---

*This markdown version is auto-generated from [https://layerv.ai/for-agents/qurl-cli-json-for-automation/](https://layerv.ai/for-agents/qurl-cli-json-for-automation/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

