§ Introduction

The 5 Principles

The five principles describe what a CLI needs to be genuinely useful to both human and agent consumers. They inform every design decision in murli and are reflected in its public API.

Unified Interface

One tool, two audiences. Humans and agents call the same commands with the same flags. murli routes output based on context — whether stdout is a TTY, or whether --agent is passed — without branching in application code.

Self-Describing Tools

Agents do not read documentation. They query tools at runtime. Every command wrapped by murli exposes --schema (per-command JSON schema) automatically. The root command exposes a describe subcommand that dumps the full command tree as a single JSON document. Both are mounted with no engineer involvement.

Actionable Errors

An error that states "something went wrong" gives an agent nothing actionable. Every error in murli carries structure: what failed (message), whether retrying will help (recoverable), what to do next (suggestion), valid alternatives (valid_values), and how long to wait if applicable (retry_after_ms). The exit code distinguishes the failure category: user error (1), tool error (2), timeout (4), not found (5), permission (6), conflict (7), rate limited (8), cancelled (9).

Intentional Mutations

State-changing operations should not execute silently when called non-interactively. murli injects --force / --yes on all commands. Handlers check w.IsForced() to decide whether to proceed. --dry-run is also injected; handlers check w.IsDryRun() and call w.WritePlan() to show what would happen without doing it.

Bounded Context

Agent sessions run many commands. Output designed for human reading — repeated status lines, progress bars, ANSI decoration — consumes tokens at scale. murli provides consecutive line deduplication in the logger (identical adjacent lines are collapsed), structured ProgressEvent for typed progress over NDJSON, and a --quiet flag convention to suppress everything except the final result.

These principles are drawn from practitioner research: Cloudflare's Wrangler rebuild, Google Workspace CLI, Trevin Chow's agent-native CLI work, the RTK project, and Speakeasy's documentation on retrofitting structured output. The full background is at allankent.com/garden/projects/murli.