Skip to main content
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 <agent>.
  • 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:

​
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 <agent> 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. 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. See Connect for setup, key placement, recovery, and exit codes.