helmr status and helmr doctor

helmr status --project PROJECT --env ENVIRONMENT
helmr status --offline --json
helmr doctor --project PROJECT --env ENVIRONMENT --json

status reports what exists. doctor checks the health of what exists. An empty Environment, no current deployment, no Agents and no Slack connections are valid states. Neither command creates resources, starts model calls, changes credentials or repairs anything automatically.

Both accept --api-url, --project, --env and --json. status also accepts --offline. Diagnostic requests share a 30-second deadline.

Context and credentials

The report identifies the source of the server, Project and Environment:

  • Server: --api-url, then HELMR_API_URL, then the API-key default origin or the saved login’s origin, following normal CLI credential selection.
  • Project: --project, then HELMR_PROJECT.
  • Environment: --env, then HELMR_ENV.

Other Environment commands resolve scope the same way. No Project or Environment context is saved.

With a saved login and no selected scope, the commands report identity and skip Environment inspection. Selecting only one of Project or Environment is an error. An API key is already Environment scoped, so selecting scope is optional with it. A selected Project or Environment is sent to the server, which reports an error when the key belongs elsewhere.

Credentials are described by kind, source and presence, never their value or a prefix. Expiry is null because the current credential store and APIs do not expose it. Offline mode makes no network requests and does not read the OS credential store: saved credential presence is null (unknown), while an API key in the environment can be reported as present. Server state and identity remain null offline. Online commands use the existing OS credential store normally.

Reported state and health

The commands read the current deployment, its Agents, up to ten recent Sessions, and Environment attention counts when available. Agent listings follow all pages; Session output includes a cursor if more Sessions exist. No model requirement is inferred from an Agent name, harness or Secret name.

doctor reports existing Session holds and failed Turns as problems. With a saved login, it uses the server’s Environment-wide attention counts. With an API key, it checks open Sessions among the latest ten Sessions. A failed Turn requires attention only while it is the latest Turn in an open Session and terminated within the past 24 hours; a newer Turn or Session closure clears that condition. For API keys, this is a bounded view, not an Environment-wide health guarantee. Questions awaiting a reply are reported as state, not failures.

Members with agent_connections.read using a saved login can inspect Slack connections for permitted retained Agents, including Agents absent from the current deployment. Existing incomplete, disconnected or unauthorized connections need a human to complete or repair them. A missing connection is not a failure. Where a workspace connection exists, doctor reports the caller’s Slack identity link. A missing personal link is optional and does not fail the check; link it through the Agent’s first-mention prompt when you want to use that Agent. Members without that permission, API keys and servers without Slack management available explicitly skip Slack management inspection.

The existing server readiness probe checks database readiness. It does not prove Worker capacity. Deployed Secret binding references, capacity and failed local build/upload attempt history are explicitly skipped because the current read APIs do not expose them. A successful report does not establish model-key validity or an end-to-end Slack reply.

JSON and exit status

JSON output is one object, including on diagnostic failure. Its schema is helmr.status/v1 or helmr.doctor/v1; fields include cli_version, offline, api_url, project, environment, credential, identity, live and checks. Each check has an id, status (pass, fail, error, or skip) and message. A remedy, when provided, includes a title and requires_human. Skipped checks explain their limits. Unknown live state is null; successful empty lists are [].

Both formats use the same exit status:

Command Exit 0 Exit 1
status Requested state was read, even if resources have problems. State could not be read or configuration is invalid.
doctor No executed check found a problem. Review skipped checks for unmeasured areas. A check found a problem or could not be completed.

The report goes to stdout. Command errors go to stderr. Diagnostics do not include upstream error response bodies, which may contain sensitive data.