> ## Documentation Index > Fetch the complete documentation index at: https://runinfra.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Connect JSON output > Read Connect newline-delimited JSON records, fields, and command ordering. Add `--json` to a Connect command, for example `npx @runinfra/connect status --json`. Read stdout as newline-delimited JSON: each nonempty line is one complete object with a string `kind`. Do not parse stdout as one JSON array. Narration, warnings, recovery paths and launch instructions go to stderr, not stdout. Warnings still appear when narration is quiet. JSON mode does not open an interactive sign-in or confirmation prompt. Consume the exit code as well as every record. A command can emit useful records and then fail. In particular, configured precedes verification and is not final success. A successful probe checks API access, not whether the agent restarted or received its required launch environment. Structured strings retain their punctuation, including paths, model names, identifiers, hashes and object property names. Secret redaction and removal of unsafe terminal control characters still apply. Sensitive fields such as `apiKey`, `authorization`, `password`, `secret` and `token` are redacted. Known key-shaped strings are redacted even inside nested values and property names. This safety filtering is the exception to lossless values. Human error messages and hints also omit private diagnostic information; use a separately reported recovery path when one is available. Do not use prose as a machine identifier. Human narration also preserves dynamic paths and launch-command punctuation. Refusal diagnostics suppress any nonempty environment value whose name contains KEY, TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL, AUTH, BEARER, COOKIE, SESSION or PRIVATE, regardless of length or name casing. Other environment values of eight or more characters and `rp_` tokens remain protected. If a refusal cannot be shown safely, Connect uses a fixed recovery message. Rerun flags come from the typed plan recommendation or the user's options, never from refusal prose. Fields listed below are required unless marked optional. Nullable means a field is present with JSON `null`, not omitted. Integers are JSON numbers. Times are strings in ISO 8601 format. Counts and record order describe one invocation, not a fixed schema-wide number of lines. Accept additional fields and unknown kinds so additive changes do not break your script. ## Record reference ### config-conflict * Fields: `kind: "config-conflict"`, `path: string`. * Appears during `off` when a particular configuration file prevents safe cleanup or restoration. Usually one immediately before an `error`; earlier recovery records can already exist. * The path is the affected configuration file, not a snapshot. It is subject to secret and control-character filtering, but not typography rewriting. ### configured * Fields: `kind: "configured"`, `agent: string`, `model: string`, `snapshotId: string`. * Appears once after `on` has saved configuration and connection state. It follows the `diff` records and precedes the probe. It is not emitted by key rotation. * `snapshotId` identifies the snapshot immediately before this `on`, not necessarily the original snapshot used by `off`. Repeated `on` can snapshot an already-connected configuration. * configured precedes verification and is not final success. Wait for the probe and exit code. ### diff * Fields: `kind: "diff"`, `path: string`, `added: integer`, `removed: integer`. * Appears once per proposed file in `on`, in the order files are planned. Counts describe the displayed line change, not bytes. * It appears before confirmation and before any native file write. A refused confirmation can leave `diff` records followed by `error`, with no `configured` or `probe`. Use `--yes` with machine-mode `on` to grant confirmation. * Permission policy is disclosed for every planned file on stderr before these records. It does not add JSON fields or records. A measured existing mode can establish a permission change; an unknown mode does not. Windows privacy remains unverified. ### doctor * Fields: `kind: "doctor"`, `agent: string or null`, `ok: boolean`, `link: string`, `message: string`. * Optional failure fields: `hint: string`, `status: integer`, `retryAfterSeconds: number`. Caught errors relay a supplied hint after the message on stderr and in the record. Both are redacted using the saved key. An API error supplies `status`. Its retry delay is included only when known, including zero. * Returned probe failures also have `httpStatus: integer or null`, `reason: string`, `retryAfterSeconds: number or null`. These have the same meaning as the failure fields under `probe`. A returned failed probe keeps its nullable fields even when no response or delay is available. Its message and reason are redacted using the saved key. It does not add `status` or `hint`. * All of these additional fields are absent on successful checks. Other local failures do not invent HTTP facts. API `status` and probe `httpStatus` describe different failure sources. * Human rate-limit guidance prints the reported wait, including zero and fractional seconds. When the delay is unknown it says so and suggests retrying later. This narration adds no fields to a returned probe check and does not promise an automatic retry. * `agent: null` means a shared credentials or model-discovery check failed. Otherwise the record describes the named agent. * `link` is `key`, `base_url`, `model`, `endpoint`, `config`, `manual` or `not-connected`. * Appears once per completed check. A shared failure produces one record and stops the checks. Otherwise `doctor` visits all registered agents in registration order, or just the agent in `doctor `. * A `manual` or `not-connected` result can have `ok: true` without making any API probe. An `endpoint` success does not verify restart. Any failed check makes the command end with an `error` after the check records. An earlier failure can prevent all `doctor` records. ### error * Fields: `kind: "error"`, `code: string`, `message: string`, `hint: string or null`, `exitCode: integer`. * Optional HTTP fields: `status: integer`, `retryAfterSeconds: number`. These come from API errors, including wrapped post-write probe failures, when known. A wrapped returned probe maps its `httpStatus` to `status`; a thrown probe preserves an available HTTP status and retry delay. Unknown HTTP fields are omitted, not set to null. Zero is a known delay. Fractional seconds are preserved. Delay reporting does not promise an automatic retry. * Appears once for a handled command failure, after any earlier records, and is the last record. A process killed externally or unable to write stdout cannot guarantee a final record. * `hint: null` means no separate action hint was supplied. Messages and hints are diagnostic text, not lossless paths or identifiers. * Doctor's final summary error does not repeat check metadata. Read its preceding `doctor` records. A wrapped post-write failure is still `probe_failed`; a returned `probe` retains its own nullable HTTP facts as well. A thrown post-write probe still emits no probe record. Its final error and saved-settings handoff remain, with known HTTP facts carried by the error. The final handler does not repeat that handoff's human summary or hint. * Exit codes remain phase-sensitive. A rejected login key is 3 and a login credits rejection is 4; a failed post-write probe, including HTTP 401 or 402, is 5. Rate limiting is 5. Incomplete key rotation is 6 even if its individual probe failed for another reason. * Other error groups are usage or unsupported runtime 2, unavailable agent or entitlement 4, changed configuration or integrity 6, local storage 7, missing consent 8, refused consent 9, interruption 130 and an unexpected failure 1. Use `code` for the specific cause. ### help * Fields: `kind: "help"`, `text: string`. * Appears once for an accepted help invocation such as `npx @runinfra/connect --help --json`. `text` contains the command help, including newline characters escaped within the JSON string. No setup or API request is performed. ### key-rotate This kind has per-agent records and a final summary. Check `summary === true` before reading `updated`, because it has a different type in the two forms. Per-agent fields: * `kind: "key-rotate"`, `agent: string`, `updated: boolean`, `probed: boolean`. * Optional `skipped: true` is present for an agent skipped because its configuration is missing, modified or no longer supported. It is absent for an attempted update. `summary` is absent. * `updated: true` means the connection update completed, including its saved state. `probed: true` means API verification passed. An agent may be updated but not verified. `updated: false` on a failed attempt is not proof that no bytes changed; follow recovery diagnostics. * At most one record per considered agent. Skips and preparation failures are reported during preparation, before credentials are saved. Prepared agents are updated in saved connection order; a returned probe result precedes that agent's rotation record. An update failure before probing has no probe record. A preparation failure stops rotation; agents not yet considered have no record. Summary fields: * `kind: "key-rotate"`, `summary: true`, `credentialsSaved: boolean or null`, `updated: string[]`, `skipped: string[]`, `failed: string[]`. * Exactly one summary is emitted when the rotation action finishes or throws, including when no agents are connected or acquisition/preparation fails. It follows every per-agent record. If rotation fails, the command's `error` follows the summary. * `credentialsSaved` is true when the credential save completed. False means no replacement credential save was attempted. Null means a save was attempted but completion could not be confirmed; the file may already contain the new key. * `updated` lists completed connection updates, `skipped` lists skipped agents, and `failed` lists agents whose preparation, update or probe failed. Lists are in encounter order. An agent whose update completed but probe failed appears in both `updated` and `failed`. Empty lists are emitted, not omitted. The lists do not claim that unvisited agents were processed. * A failure before the rotation action starts, such as invalid arguments or an unavailable configuration lock, produces only the applicable `error`, without a rotation summary. * Rotation does not revoke old keys. Revoke them in the dashboard only after checking every agent. Recovery snapshots can contain old keys. Helper mode does not remove Connect's saved credentials or retained snapshots. Example with no connected agents: ```json theme={"dark"} {"kind":"key-rotate","summary":true,"credentialsSaved":true,"updated":[],"skipped":[],"failed":[]} ``` ### login * Fields: `kind: "login"`, `workspaceId: string or null`, `keyPrefix: string`. * Appears once after validation and saving local credentials. A failure before that point emits no `login` record. * `workspaceId: null` means workspace scope was validated but the API did not supply a workspace identifier. `keyPrefix` is a redacted recognition prefix, never a usable key. * Machine-mode `on` requires an existing login; it does not silently sign in. Key rotation validates its replacement without emitting `login`. ### logout * Fields: `kind: "logout"`, `removed: boolean`, `agentsUnchanged: true`. * Appears once after attempting removal of local Connect credentials. `removed: false` means no credentials file was present, not an API failure. * Agents and retained snapshots are not removed. This is not remote key revocation or restoration of agent configuration. ### manual * Fields: `kind: "manual"`, `agent: string`, `steps: string[]`. * Appears once for `on` or `off` with a manual-only agent, including forced `off`. Steps are in display order. No login, automatic file write or probe is claimed. These commands do not read connection state or resolve the pending journal. There is no following `off` record or `configured` record. ### off Three forms describe the outcome: * Restoration: `kind: "off"`, `agent: string`, `restored: true`, `snapshotId: string`. * Cleanup with a missing original snapshot: `kind: "off"`, `agent: string`, `restored: false`, `cleaned: true`, `bestEffort: boolean`. * No recorded connection: `kind: "off"`, `agent: string`, `restored: false`, `bestEffort: boolean`. Fields belonging to another form are absent, not null. `bestEffort` reports whether recognizable settings were changed; `false` can mean nothing was changed. It is never proof of restoration. One `off` record appears after completed restoration or cleanup, following any `recovery-snapshot` records. A manual-only agent emits `manual` instead. A failed operation emits `error` instead of `off`. For restoration, `snapshotId` is the original snapshot from before the first active connection, retained across repeated `on` and key rotation. With older saved state it falls back to that connection's recorded snapshot. Forced cleanup without a snapshot is credential cleanup, not restoration. ### paused-models * Fields: `kind: "paused-models"`, `models: string[]`. * Appears at most once after all agent rows in the all-agent `status` command, only when saved credentials are available, discovery succeeds and at least one model is paused. The array is nonempty and follows catalog order. * Its absence does not prove that no models are paused: discovery may not have run or may have failed. A failed discovery reports a warning on stderr and leaves the local status rows usable. Agent-scoped status does not emit this kind. ### pending-recovery * Fields: `kind: "pending-recovery"`, `agent: string`, `startedAt: string`, `snapshotId: string`, `command: string`. * Appears when an interrupted setup contains mixed or modified files that prevent safe continuation. It precedes the terminal `error`. The first blocking operation stops that check, so an invocation normally emits at most one. * `snapshotId` is the original snapshot to restore, not the snapshot immediately before the interrupted update. `startedAt` is that update's recorded start time. `command` contains `npx @runinfra/connect off --force`, with the actual agent name. The warning and error hint use the same command. Review and preserve edits before running it. * Read-only status and doctor can emit this record too. A successful automatic recovery or a scoped forced `off` may emit none, so absence does not establish that no interruption occurred. ### probe Success fields: * `kind: "probe"`, `agent: string`, `ok: true`, `requestId: string`, `cachedTokens: integer or null`, `model: string`. * `cachedTokens: null` means the API did not report a valid nonnegative cache count. Zero is a reported value. Request and model identifiers retain their supplied punctuation, subject to safety filtering. Failure fields: * `kind: "probe"`, `agent: string`, `ok: false`, `link: string`, `message: string`, `httpStatus: integer or null`, `reason: string`, `retryAfterSeconds: number or null`. * `link` is `key`, `base_url`, `model` or `endpoint`. * `httpStatus` is the response status, including 200 for a malformed successful reply. It is null when no usable response was returned to the check. * `reason` is `key_rejected`, `key_denied`, `credits_required`, `rate_limited`, `base_url_invalid`, `model_not_found`, `http_error`, `invalid_response`, `model_mismatch`, `missing_request_id`, `missing_stop_reason`, `incomplete_response`, `empty_completion` or `missing_finish_reason`. A request exception uses its safe error code, such as `network`, `server_error` or `unexpected`. * `retryAfterSeconds` reports a valid `Retry-After` numeric delay or HTTP date as seconds, including zero. If that header is absent, a valid `retry-after-ms` is converted to seconds and can be fractional. Absent or invalid delay information is null. This field does not promise an automatic retry, and values can exceed the automatic retry budget. * Success-only fields are absent from failures and failure-only fields are absent from successes. One probe record appears for each returned setup or rotation check. `on` emits it after `configured`; rotation emits it before that agent's `key-rotate` record. A failure before a probe returns can leave no probe record. Doctor emits its own `doctor` records, not `probe`. A failed post-write check does not roll back the saved settings. ### recovery-snapshot * Fields: `kind: "recovery-snapshot"`, `snapshotId: string`. No `agent` field is present; use the invoked command's agent. * Appears in `off` before changing current configuration during fallback cleanup or before overwriting later edits with `--force`. There can be none, one for a group of cleanup edits, or one per changed file during forced restoration. * The snapshot contains current bytes saved before recovery. It is not the original snapshot restored by `off`. A later failure can leave this record without a successful `off` record. Keep it until you have checked the result. ### status * Fields: `kind: "status"`, `agent: string`, `support: string`, `status: string`, `model: string or null`, `connectedAt: string or null`. * `support` is `ready`, `preview` or `manual`. `status` is `active`, `modified` or `missing`. * Appears once for agent-scoped status, or once per registered agent in registration order for all-agent status. Stop interpreting completeness if a later `error` appears. * `active` means recorded file hashes match, not that the agent restarted or an API request succeeded. `modified` includes a partly missing file set. `missing` includes no recorded connection or all recorded files being absent. `model` and `connectedAt` are null without a recorded connection; they may remain populated for modified or missing files. ### version * Fields: `kind: "version"`, `version: string`. * Appears once for an accepted version invocation such as `npx @runinfra/connect --version --json`. No setup or API request is performed. ## Ordering by command Every command below can stop with `error` before its first expected success record, including because it cannot read configuration or obtain a required lock. Records already emitted remain valid observations, not a transaction-wide success claim. | Command | Normal record order and conditional records | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--help` | One `help`. | | `--version` | One `version`. | | `login` | One `login` after the key is validated and saved. | | `logout` | One `logout`, whether or not local credentials existed. | | ` on --yes` | One `diff` per proposed file, then one `configured`, then one returned `probe`. A failed check adds `error`. A refusal before saving can end after the diffs. A manual agent emits only `manual`. | | ` off` | Zero or more `recovery-snapshot` records, then `off`; a blocking file can instead add `config-conflict` followed by `error`. A manual agent emits only `manual`, without reading state or the pending journal. | | ` status` | One `status`, or a blocking `pending-recovery` followed by `error`. | | `status` | All `status` rows, then optional nonempty `paused-models`. A blocking interrupted setup can produce `pending-recovery` followed by `error` instead. | | `doctor []` | One shared failure or one `doctor` per completed agent check. Any failed check adds a final `error`. A blocking interrupted setup can produce `pending-recovery` followed by `error` before checks. | | `key rotate` | Preparation-time skipped or failed `key-rotate` records, then each prepared agent's optional `probe` and `key-rotate`, then one summary `key-rotate`. Failures add a final `error`. Acquisition can fail before any agent record. A blocking interrupted setup can produce `pending-recovery`, the summary and `error`. | Snapshots are retained rather than automatically deleted. Keep the original snapshot for restoration and inspect any recovery snapshot before discarding it. Never treat `configured`, a local `active` status, credential cleanup or the mere presence of a rotation summary as final verification. ## Related See [Connect](/docs/tools-sdks/connect) for setup, key placement, recovery, and exit codes.