lango status¶

Show a unified status dashboard combining health, configuration, and feature information.

Synopsis¶

lango status [flags]
lango status dead-letter-summary [flags]
lango status dead-letters [flags]
lango status dead-letter <transaction-receipt-id> [flags]
lango status dead-letter retry <transaction-receipt-id> [flags]

Description¶

The status command provides a single-screen overview of your Lango agent. It shows system info, active channels, and which features are enabled or disabled. Displayed provider/model labels, feature names/details, channel names, dead-letter labels, dead-letter summary JSON labels, dead-letter list/detail JSON payload fields, and JSON error payload text are normalized to plain single-line text before rendering or serialization, and both the collected status model and dead-letter retry result payloads use the same normalized form for replay and JSON output. The root dashboard path also writes through the Cobra command output stream, so test harnesses and wrappers can capture the same human-readable output that an operator sees. The --output flag is validated before status bootstrap or dead-letter bridge work begins; only table and json are accepted. Live /health feature metadata is normalized the same way before it is stored under serverInfo.features, so root status JSON does not preserve raw control-sequence text from the gateway. Injected build version text is normalized with the same contract before it reaches the top-level version field. The same plain single-line contract now also applies to dead-letter retry confirmation prompts and non-JSON retry errors when they echo a transaction receipt ID back to the operator. Dead-letter filter validation errors apply the same rule when they echo an invalid flag value back to the operator. As a backstop, any non-JSON status command failure is sanitized again at the shared command boundary while still preserving the original wrapped cause for tests and callers.

Live mode: When the gateway server is running, status probes the /health endpoint and reports whether the server is healthy.

Config-only mode: When the server is not running, status still shows configuration-based information (profile, provider, model, features, channels).

The status command also exposes dead-letter operator views:

• lango status dead-letter-summary
• lango status dead-letters
• lango status dead-letter <transaction-receipt-id>
• lango status dead-letter retry <transaction-receipt-id>

Flags¶

When --addr is omitted, lango status probes the configured server.host and server.port, falling back to http://localhost:18789 only when those values are unavailable. When --addr is supplied, lango status probes the normalized explicit address and the gateway field reports that same normalized address. Unknown --output values such as yaml fail fast with an actionable error before the command contacts the gateway or loads dead-letter status tooling.

Dead-Letter Subcommands¶

lango status dead-letter-summary¶

Show a global overview of the current dead-letter backlog.

The current summary surface includes:

• total_dead_letters
• retryable_count
• top_limit
• by_adjudication
• by_latest_family
• by_reason_family
• grouped reason-family buckets derived from each backlog row's current latest_dead_letter_reason
• initial taxonomy:
  • retry-exhausted
  • policy-blocked
  • receipt-invalid
  • background-failed
  • unknown
• classification is case-insensitive and falls back to unknown when no built-in heuristic matches
• by_actor_family
• grouped actor-family buckets derived from each backlog row's current latest_manual_replay_actor
• initial taxonomy:
  • operator
  • system
  • service
  • unknown
• classification is case-insensitive and falls back to unknown when no built-in heuristic matches
• top_latest_dead_letter_reasons
• top 5 latest dead-letter reasons
• each item includes:
  • reason
  • count
• aggregated from each backlog row's current latest_dead_letter_reason
• remains available alongside by_reason_family so operators can see both grouped families and raw latest reason strings
• top_latest_manual_replay_actors
• top 5 latest manual replay actors
• each item includes:
  • actor
  • count
• aggregated from each backlog row's current latest_manual_replay_actor
• remains available alongside by_actor_family so operators can see both grouped families and raw latest actor strings
• by_dispatch_family
• grouped dispatch-family buckets derived from each backlog row's current latest_dispatch_reference
• current classifier recognizes common leading tokens such as dispatch, queue, worker, bridge, webhook, and unknown
• aliases such as job, runner, and task normalize to worker
• otherwise the first normalized token is preserved as-is so unfamiliar prefixes still surface deterministically
• top_latest_dispatch_references
• top latest dispatch references
• each item includes:
  • dispatch_reference
  • count
• aggregated from each backlog row's current latest_dispatch_reference
• remains available alongside by_dispatch_family so operators can see both grouped families and raw latest dispatch strings
• recent_dead_letter_trend
• a recent time-window summary over latest_dead_lettered_at
• includes window, bucket, windowed_count, and per-bucket counts
• rendered in table output as Recent dead-letter trend
• rendered in JSON output as recent_dead_letter_trend

Flags:

Examples:

lango status dead-letter-summary
lango status dead-letter-summary --output json
lango status dead-letter-summary --top 10
lango status dead-letter-summary --trend-window 72h --trend-bucket 24h

Table output includes By reason family, By actor family, By dispatch family, and Recent dead-letter trend sections while preserving the raw Top Latest Dead-Letter Reasons, Top Latest Manual Replay Actors, and Top Latest Dispatch References sections. JSON output includes by_reason_family, by_actor_family, by_dispatch_family, and recent_dead_letter_trend.

lango status dead-letters¶

List the current dead-lettered post-adjudication backlog.

Flags:

Examples:

lango status dead-letters
lango status dead-letters --query tx-123
lango status dead-letters --adjudication release --output json
lango status dead-letters --latest-status-subtype dead-lettered
lango status dead-letters --latest-status-subtype-family manual-retry
lango status dead-letters --any-match-family retry
lango status dead-letters --manual-replay-actor operator:alice
lango status dead-letters --dead-lettered-after 2026-04-25T09:00:00Z --dead-lettered-before 2026-04-25T18:00:00Z
lango status dead-letters --dead-letter-reason-query exhausted
lango status dead-letters --latest-dispatch-reference dispatch-7
lango status dead-letters --offset 50 --limit 25 --output json

lango status dead-letter <transaction-receipt-id>¶

Show the current canonical dead-letter status for one transaction.

The output includes:

• canonical receipts-backed status
• latest retry / dead-letter summary
• latest_background_task when present

Flags:

Examples:

lango status dead-letter tx-123
lango status dead-letter tx-123 --output json

lango status dead-letter retry <transaction-receipt-id>¶

Request a retry for a dead-lettered post-adjudication execution.

Behavior:

• reads the current detail status first
• requires can_retry=true
• rejects before mutation when can_retry=false
• precheck rejection is surfaced as a retry-precheck error, not a mutation failure
• prompts for confirmation by default
• the confirmation prompt is driven through the shared confirmation helper on top of Cobra command streams
• --yes skips the prompt
• reuses the existing retry control path
• injects a local default operator principal when the invocation context does not already carry one, so replay policy does not evaluate an empty actor
• --actor overrides that fallback and forces the retry request to run under an explicit replay actor principal
• success output means the retry request was accepted on the retry path, not that settlement execution already completed
• captures an immediate follow-up status snapshot after acceptance
• --wait keeps polling follow-up status until the observed follow-up changes or the wait timeout expires
• table output renders follow-up polling count, timeout/error state, and a structured follow-up block when available
• json output returns a structured retry-request result payload with transaction_receipt_id, result, message, follow_up, follow_up_error, poll_count, and timed_out
• dead-letter status subcommands return structured JSON errors when --output json is selected:
• result: "error"
• error: "<message>"
• follow_up includes observed_at, dead-letter/retryable booleans, latest subtype/family/reason/retry-attempt/dispatch data, and background_task when present
• invocation failures are surfaced separately as retry-request failures

Flags:

Examples:

lango status dead-letter retry tx-123
lango status dead-letter retry tx-123 --yes
lango status dead-letter retry tx-123 --yes --output json
lango status dead-letter retry tx-123 --yes --actor operator:ci
lango status dead-letter retry tx-123 --yes --wait --wait-interval 1s --wait-timeout 30s

Output Sections¶

System¶

Channels¶

Lists all enabled messaging channels (telegram, discord, slack).

Features¶

Shows each feature as enabled or disabled:

Examples¶

Full status dashboard (table format):

lango status

Machine-readable JSON output:

lango status --output json

Probe a custom gateway address:

lango status --addr http://192.168.1.10:18789/

The command probes http://192.168.1.10:18789/health and reports "gateway": "http://192.168.1.10:18789" after normalizing the explicit address.

JSON Schema¶

When using --output json, the response follows this structure:

{
  "version": "1.2.3",
  "profile": "default",
  "serverUp": true,
  "gateway": "http://192.168.1.10:18789",
  "provider": "openai",
  "model": "gpt-4o",
  "features": [
    {
      "name": "Knowledge",
      "enabled": true
    },
    {
      "name": "MCP",
      "enabled": true,
      "detail": "2 server(s)"
    }
  ],
  "channels": ["telegram", "discord"],
  "serverInfo": {
    "healthy": true
  }
}

The serverInfo field is only present when the server is reachable. The detail field on features is optional and provides additional context (e.g., MCP server count).