---
title: CLI Backend-Aware Display Patterns
read_when:
  - "adding CLI commands that behave differently for issue vs planned-PR plans"
  - "routing between gh issue and gh pr commands based on plan backend"
  - "understanding how plan_backend affects CLI output"
tripwires:
  - action: "using gh issue view on a plan without checking plan backend type"
    warning: "Planned PR plan IDs are PR numbers, not issue numbers. Using gh issue view on a planned-PR plan produces a confusing 404. Route to gh pr view based on backend type."
    score: 7
---

# CLI Backend-Aware Display Patterns

CLI commands that interact with plans must handle two backends: `github` (issue-based) and `github-draft-pr` (draft PR-based). This document covers the patterns for routing behavior based on backend type.

## Three Detection Patterns

The codebase uses three approaches to detect the active backend, each suited to different contexts:

### Pattern 1: Interface Delegation (Preferred)

<!-- Source: src/erk/cli/commands/learn/learn_cmd.py -->

Commands that operate on plan metadata should use the `plan_backend` abstract interface without checking the type. Both backends implement the same methods. See `src/erk/cli/commands/learn/learn_cmd.py` for an example of interface delegation without backend branching.

Use this when the operation is the same regardless of backend — the abstraction handles routing internally.

### Pattern 2: Provider Name Check (Exec Scripts)

<!-- Source: src/erk/cli/commands/exec/scripts/handle_no_changes.py:195 -->

Exec scripts that need different behavior call `get_provider_name()` on the backend and compare against the provider string `"github-draft-pr"`. See [`handle_no_changes.py`](../../../src/erk/cli/commands/exec/scripts/handle_no_changes.py) around line 195 for an example.

Use this in exec scripts where `require_plan_backend()` is already in scope.

### Pattern 3: Direct Comparison (TUI)

<!-- Source: src/erk/tui/commands/registry.py:31-33, _is_github_backend -->

The TUI command palette uses the `_is_github_backend()` predicate in [`registry.py`](../../../src/erk/tui/commands/registry.py), which compares `ctx.plan_backend` directly against the `"github"` string. Use this for availability filtering where you need a boolean check.

## Terminology Routing

When displaying plan information to users, use backend-appropriate terminology:

| Concept      | Issue Backend   | Planned PR Backend |
| ------------ | --------------- | ------------------ |
| Plan storage | "issue"         | "planned PR"       |
| Plan ID      | Issue number    | PR number          |
| View command | `gh issue view` | `gh pr view`       |
| Plan label   | `erk-plan`      | `erk-plan`         |

## When to Use Each Pattern

| Scenario                                          | Pattern              |
| ------------------------------------------------- | -------------------- |
| Metadata reads/writes                             | Interface delegation |
| Different GitHub CLI commands needed              | Provider name check  |
| Command visibility filtering                      | Direct comparison    |
| Output text differences ("issue" vs "planned PR") | Provider name check  |

## Related Topics

- [Backend-Aware TUI Commands](../tui/backend-aware-commands.md) — TUI-specific command filtering by backend
- [Planned PR Backend](../planning/planned-pr-backend.md) — Backend architecture and selection
