1# JSON output23Every command accepts the global `--json` flag before or after its subcommands. Finite4commands write exactly one JSON value to stdout:56```json7{"schema_version":1,"ok":true,"command":"daemon.status","result":{"running":true,"start_hints":[]}}8```910Every record carries `schema_version: 1`; consumers should reject versions they do not11understand rather than guessing at a changed shape.1213Failures are JSON on stdout and retain meaningful exit codes: `1` for runtime failures and14`2` for command-line usage errors.1516```json17{"schema_version":1,"ok":false,"command":"service.host","error":{"kind":"runtime","message":"…","causes":[],"suggestions":["Run `devsite service host --help` for valid arguments."]}}18```1920Help is structured too: `devsite link set --json --help` succeeds with command `help` and21puts the complete command-specific help in `result.text`. Usage and runtime errors include22recovery suggestions suitable for either display or direct agent consumption.2324`devsite connect --json` and `devsite daemon run --json` are resident processes. They emit25one JSON value per line so consumers can process lifecycle events as NDJSON. Human logs and26transport warnings remain on stderr and never contaminate JSON stdout.2728JSON mode is non-interactive. In particular, `devsite login --json` requires its ticket as an29argument rather than prompting on stdin.3031## Inventory, plans, and diagnostics3233`devsite resources list --json` joins the control plane's owned resources with this34machine's hosted-service config. Service states distinguish `serving_here`,35`configured_here`, and `not_configured_here`; `local_only_services` identifies local36entries whose remote resource is already absent.3738Resource mutations accept `--plan` (`--dry-run` is an alias):3940```console41devsite link set --name docs --url https://example.com --public --plan --json42devsite service remove postgres --plan --json43```4445Plans return `applied: false` with validated field, recipient, effect, and local-config46changes. They never write remote or local state. Applied mutations retain their existing47result fields and add `applied: true` plus the authoritative plan the server applied.4849`devsite doctor --json` returns a report rather than treating an unhealthy installation as50a command failure. The envelope remains `ok: true` when the report was produced; inspect51`result.healthy`, `result.checks`, and `result.actions`. Doctor checks endpoint identity,52file permissions, server/API compatibility, the pinned signing key, credential binding,53daemon registration, and remote/local resource drift. It does not open connections to54hosted services.5556## Delegated access5758`devsite access request SERVICE --request FILE --key FILE --json` creates a public signed59request and a separate private requester endpoint key. Its result contains60`request`, `request_path`, `key_path`, and `handoff: "share_request_only"`. The request61object has schema version, request id, signed service keyword, requester endpoint id, expiry,62and proof. The two paths must differ and must not exist.6364`devsite access resolve KEYWORD --json` requires a machine credential enrolled with the65`service_grants:issue` scope. It returns matching accessible services with resource id,66name, optional owner handle, and exact-name-match state.6768`devsite access grant --request FILE --plan --json` validates and resolves the signed69request without issuing a grant. If resolution is ambiguous, supply an approved70`--resource res_…`. The plan returns a server-signed `approved_plan` token covering the71exact granting party credential, request, resource, endpoint, and expiry. Apply with72`--approved-plan dsp_…`; changed inputs are rejected. A successful apply returns the request73id, resource id, name and owner, requester endpoint id, expiry, short-lived `dss_…` grant,74and `server`. Treat the grant as a secret and return only the grant and server to the75requester.7677`devsite access connect GRANT --key FILE --json` is resident NDJSON. It validates that the78grant was issued by the granting party and is bound to the supplied key. It then emits the same `listening`,79`connection`, error, and shutdown lifecycle records as ordinary `connect`.