Skip to content

PATTERN Cited by 1 source

Deep link to UI from CLI

A CLI that drives a system with a rich web UI emits deep links back into the UI — precise URLs that land the human at the exact dashboard / alert / SLO / trace view that the agent is working with, rather than a "go navigate to the thing" hand-wave. The agent does the work in the terminal; the human picks up in the UI.

When to use this pattern

  • The CLI is driven primarily by agents, but there's still a role for human review, approval, or escalation.
  • The target system has a rich UI with stable deep-linkable routes.
  • Handing a human a URL is dramatically cheaper than asking them to recreate the agent's navigation by hand.

The verbatim canonical statement

From the gcx launch post:

"Open a deep link into Grafana Cloud the moment a human needs to look."

The pattern is documented for Grafana at grafana.com/docs/grafana/latest/developer-resources/mcp/guides/generate-deeplinks-to-grafana — itself referenced from the MCP / agent-guide surface, not the general-user docs. The audience is explicitly agent-builders.

Mechanism

The agent's workflow ends (or pauses) with an emitted URL:

$ gcx alerts investigate --alert-id 42 --output yaml
  … analysis …
  deep_link: https://my-org.grafana.net/alerting/grafana/42/edit?tab=history
  summary: "Alert 42 fired 17 times this week, mostly at 03:00 UTC;
            recommend tightening `for` clause from 5m to 15m."
$

The agent returns {deep_link, summary} to the human (Slack, a ticket, an IDE panel); the human clicks, lands at the exact alert edit view with the firing-history tab pre-selected, and makes the call.

  • Context density. The UI shows charts, sourcemaps, related dashboards, escalation history, annotations, and runbooks — none of which fit in a text summary.
  • Trust. Humans trust what they see, not what an agent claims. Deep-linking lets the human verify the agent's analysis against the primary source in one click.
  • Navigation cost. A 5-level deep link represents a 30-second manual navigation saved per handoff. At fleet scale this compounds.
  • Ambiguity. Without the deep link, the agent has to describe navigation: "open the dashboard called checkout-api, go to panel 3, filter to the last 2 hours." The human follows imperfectly, lands in the wrong place, and either re-runs the agent or gives up.

Requirements on the UI

For the pattern to work, the target UI must have:

  • Stable route schemas for resources — /d/{uid}, /alerting/{provider}/{id}/edit, etc.
  • Query-parameter-addressable views — ?from=…&to=… for time range, ?tab=… for which panel pre-opens, ?var=… for dashboard template variables.
  • Permalink-able state — scroll position, filters, drill-down selections — captured in the URL, not in session state.

Grafana's deep-link guide canonicalises the set of stable routes for agent consumption.

Sibling patterns

Pattern When it fires
Deep link to UI (this pattern) Human review / verification / escalation needed
Pretty-printed summary in terminal Fully agent-owned end state, no handoff
MCP resource reference (opaque URI) Tool-to-tool handoff — not human-facing
Ticket with embedded screenshot Asynchronous handoff; higher cost than deep link

Composition with other CLI-agent primitives

Tradeoffs

  • URL instability. If the UI restructures its routes, old deep links break. Requires a versioned deep-link contract.
  • Auth surface. The deep link presumes the human has access — SSO / permission checks happen on the click.
  • Leaking identifiers. A deep link contains resource IDs that may be sensitive in some contexts; handoff channels must be appropriate.
  • Mobile / low-bandwidth recipients. Deep links assume a browser-capable recipient; fall back to summary + links for non-browser contexts.

Seen in

Last updated · 433 distilled / 1,256 read