Run the read-only health walk

curl --request GET \
  --url https://api.example.com/v1/doctor \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/doctor"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/doctor', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "text": "narya doctor — /Users/dev/.config/narya\n\nhome  ok  ...\n\nno findings\n",
  "version": "1.0.0",
  "home": "/Users/dev/.config/narya",
  "healthy": true,
  "findings": 0,
  "warnings": 0,
  "failures": 0,
  "checks": [
    {
      "name": "home",
      "status": "ok",
      "detail": "/Users/dev/.config/narya"
    }
  ]
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Run the read-only health walk

Runs narya doctor’s own walk over this installation — home directory, config, host lock, socket, store, sessions, package jobs, tool servers, credentials, binary and terminal — and answers both the rendered text and the structured lines behind it. Read-only throughout: every check reads, the store is opened read-only, and a finding names the command that repairs it rather than running one. It exists so a client does not have to compile the walk to offer /doctor. The walk lives with the engine, and the things a caller knows about itself that a host cannot — which binary is asking, which build produced it, what the caller’s own terminal can render, and which desktop helpers the caller can actually deliver through — travel as parameters rather than being guessed at from the host’s process. A host that is not running cannot answer this at all, which is the one case a client handles itself: it says so and names narya doctor, the command that walks a machine whose host is down. One line stays the HOST’s own fact whatever a caller says: the keychain check describes the session the host process runs in, since that is the process that stores and reads a credential.

GET

doctor

curl --request GET \
  --url https://api.example.com/v1/doctor \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/doctor"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/doctor', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "text": "narya doctor — /Users/dev/.config/narya\n\nhome  ok  ...\n\nno findings\n",
  "version": "1.0.0",
  "home": "/Users/dev/.config/narya",
  "healthy": true,
  "findings": 0,
  "warnings": 0,
  "failures": 0,
  "checks": [
    {
      "name": "home",
      "status": "ok",
      "detail": "/Users/dev/.config/narya"
    }
  ]
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Authorizations

Authorization

string

header

required

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

Query Parameters

callerVersion

string

The version of the binary ASKING. The walk compares it against the answering host's own, which is what reports a host serving your sessions from a different build than the one on disk. Omitted, the host reports its own version and that comparison cannot fire.

Maximum string length: 128

callerGeneration

string

The build job that produced the asking binary, when there was one — an extension rebuild stamps it. Reported on the binary line.

Maximum string length: 128

callerColorProfile

string

What the CALLER's terminal renders, e.g. TrueColor or ANSI256. A daemon's own stdout is a pipe, so a host asked to detect this for a client would report the absence of the client's terminal. Omitted, the host detects its own.

Maximum string length: 32

callerNotifier

string

The platform notification program the CALLER resolved on its own $PATH, e.g. notify-send or osascript, or empty for none found. The caller is the process that delivers a banner, so this is a fact about it and not about the answering host: a host started by systemd or launchd carries a minimal PATH and no desktop session, and answering from its own walk reports "no platform notifier on this machine" to a person sitting at one. Omitted entirely — as narya doctor run against a host omits it — the host walks its own $PATH.

Maximum string length: 128

callerSoundPlayer

string

The audio player the CALLER resolved on its own $PATH, e.g. paplay or afplay, or empty for none found. A fact about the caller for callerNotifier's exact reason: the caller is the process that plays the sound. Omitted, the host walks its own $PATH.

Maximum string length: 128

Response

The health walk, rendered and structured.

One health walk over an installation: the aligned text narya doctor prints, plus the same lines structured so a caller can gate on them without parsing prose. healthy, failures and narya doctor's exit code are one decision expressed three times, never three that can disagree: healthy is failures == 0, and the command's exit code is its projection. Warnings are compatible with healthy — a warning is something that works today and will bite you later — which is why the counts are carried separately and a stricter consumer can gate on warnings itself.

text

string

required

The walk as narya doctor prints it: one aligned name/status/detail line per check, each finding's remedy indented underneath, and a closing verdict. Carried so a client renders the same walk a terminal does rather than re-implementing the layout and drifting from it.

version

string

required

The version the walk reports for the binary it describes.

home

string

required

The resolved narya home directory this walk describes.

healthy

boolean

required

Nothing is broken — no fail-class line. This is what exit 0 means.

findings

integer

required

Every line that is not ok — warnings plus failures.

Required range: x >= 0

warnings

integer

required

Required range: x >= 0

failures

integer

required

Required range: x >= 0

checks

object[]

required

Every line of the walk, in the order it was checked.

Show child attributes

Overview

Host

Sessions

Messages

Events

Lanes

Monitors

Agents

Skills and commands

Permissions

Peers

Packages

Extensions

Workflows

Schedules

Providers

Records

Environments

Sharing

Refinements

Platform

Error handling

Run the read-only health walk

Authorizations

Query Parameters

Response