CLI Design

Rule

Rules for project CLIs that expose the API for local development and coding agent use.

Philosophy

  • MUSTEvery project with an API ships a companion CLI.
  • MUSTDual-mode — scripted (with args) and interactive (no args).
  • MUSTUse Commander for argument parsing in scripted mode.
  • SHOULDUse Ink (React TUI) for interactive mode in React projects.

Scripted Mode

  • SHOULD--quiet flag to suppress non-essential output.
  • SHOULDShort aliases for common flags (-m for --model, -o for --output).

Interactive Mode

  • MUSTScreen-based navigation (Home screen routes to feature screens).
  • MUSTKeyboard shortcuts documented in the UI (footer or header hints).
  • SHOULDEscape to go back, q to quit.
  • SHOULDState machine pattern for multi-step flows.

Agent Friendliness

  • MUST--json outputs structured data, not decorated text.
  • MUSTErrors in JSON mode use same structure as API errors. See api.md.
  • MUSTNo color codes or spinners when stdout is not a TTY.
  • SHOULD--help output is complete and shows all options with examples.
  • SHOULDSupport stdin piping for batch operations.

Architecture

  • MUSTAPI client shared between CLI and web app — same types, same logic.
  • MUSTSeparate argument parsing from interactive UI from business logic.
  • SHOULDConfig hierarchy: env vars > global (~/.tool/config.json) > local (.toolrc).