Kendo HQ

Appearance

CLI Decisions ​

Distilled from 4 DECISIONS.md files. Each entry is a real fork in the road. Implementation details that aren't a tradeoff are NOT here.

CLI authentication — OAuth Device Flow, not Authorization Code ​

  • Chose: RFC 8628 Device Authorization grant — CLI shows a code, user approves in the browser.
  • Rejected: Authorization Code + PKCE with a localhost redirect, OR personal access token paste.
  • Why: Authorization Code requires a redirect URI which terminals can't receive; localhost-callback variants fail behind firewalls and are unreliable in WSL. Device Flow works on local, SSH, WSL, and headless servers identically.
  • Source: KD-0237

CLI v1 scope — issues only ​

  • Chose: 7 issue commands + 3 auth commands + 2 project commands.
  • Rejected: Issues + Sprints, OR full Issues + Sprints + Time.
  • Why: Issues cover the core developer workflow; sprints/time can be added in v2 without rewriting the v1 surface.
  • Source: KD-0237

CLI tokens reuse read+write scopes ​

  • Chose: Reuse the existing scopes used by personal access tokens.
  • Rejected: New cli:use scope.
  • Why: No backend changes needed — EnforceTokenScope middleware already handles read+write. Adds nothing operationally.
  • Source: KD-0237

Tenant resolution — config file, not per-command flag ​

  • Chose: Tenant URL stored once in ~/.config/kendo/config.yaml during kendo auth login.
  • Rejected: --tenant flag with config default.
  • Why: Single-tenant per CLI config is predictable; multi-tenant users can swap config dirs as a future enhancement.
  • Source: KD-0237

Token storage — file with 0600 permissions, not OS keychain ​

  • Chose: ~/.config/kendo/tokens.json with 0600 perms.
  • Rejected: Native OS keychain (libsecret/Keychain/Credential Manager).
  • Why: Cross-platform without native dependencies; keychain can be bolted on later as opt-in.
  • Source: KD-0237

Distribution — GoReleaser + GitHub Actions on tag push ​

  • Chose: Tag cli/v* triggers cross-platform GoReleaser build (linux/macOS/windows × amd64/arm64).
  • Rejected: go install only (requires Go toolchain on user's machine), OR manual builds.
  • Why: Non-Go users need pre-built binaries; manual builds don't scale across six target triples.
  • Source: KD-0237

Binary hosting — existing R2 bucket with cli/ prefix ​

  • Chose: Reuse the central app's S3 disk with a cli/ path prefix.
  • Rejected: New public R2 bucket on a custom domain (e.g. releases.kendo.dev), OR Fly.io local storage.
  • Why: GitHub Releases aren't accessible (private repo); a separate bucket adds domain config and credential sprawl; Fly local storage is single-region and wiped on deploy.
  • Source: KD-0261

Download serving — central app proxy, not 302 redirect ​

  • Chose: Stream binaries through the central app via Storage::disk('s3')->download().
  • Rejected: Pre-signed R2 URL redirects.
  • Why: Clean URLs (central.kendo.dev/cli/download/...), enables future download tracking, avoids exposing R2 internals; ~10-15MB binaries are fine through Fly.io.
  • Source: KD-0261

Release sync — GitHub release webhook pull, not CI push ​

  • Chose: GoReleaser publishes to GitHub Releases → webhook fires → central app downloads assets via GithubAppService → writes to R2.
  • Rejected: CI step using AWS CLI to upload directly, OR GoReleaser S3 publisher config.
  • Why: Pull avoids putting R2 credentials in GitHub Actions secrets — the central app already has webhook infra, GitHub App credentials, and the S3 disk. Zero new secrets anywhere.
  • Source: KD-0261

Latest-version metadata — latest.json in R2, no database ​

  • Chose: A single cli/latest.json file in the bucket.
  • Rejected: A cli_releases table with version, released_at, platform info.
  • Why: The only runtime query is "what's the latest version?" — a JSON file answers that with zero migrations or models.
  • Source: KD-0261

Self-update — rename + replace + cleanup, not in-place overwrite ​

  • Chose: Download to temp → verify checksum → rename current to .old → move new in → verify runs → delete .old.
  • Rejected: Simple overwrite of the running binary.
  • Why: Overwrite leaves a broken CLI if the download is corrupted or interrupted; rename+replace gives a rollback path.
  • Source: KD-0261

Project tokens — exclude from profile, don't show separately ​

  • Chose: ListTokensAction filters project tokens out of profile responses entirely.
  • Rejected: Render personal tokens and project tokens in two sections on the profile page.
  • Why: Project tokens already have a dedicated UI in project settings where the right permissions are checked; duplicating that on the profile adds maintenance with no value.
  • Source: KD-0396

--limit flag — server-side query param, not client-side slice ​

  • Chose: Only expose --limit on commands whose backend route already accepts ?limit= (the search endpoints with the CappedListResourceData envelope).
  • Rejected: Client-side trim — fetch the full list, slice in cmd/, so every list command gets --limit uniformly.
  • Why: Backend has deliberately gated ?limit= to search endpoints; a CLI flag that pretends to limit while the API still ships the full set creates semantic drift between commands and lies about what the wire saw.
  • Source: KD-0308

Bundle latent envelope-parse fix into the flag PR ​

  • Chose: Fix the broken []Issue unmarshal against the new {data, meta} envelope in the same PR as the new --limit wiring.
  • Rejected: File a separate bug, block KD-0308 on it, then return.
  • Why: A new flag whose acceptance criterion ("results truncated to N") is observable on the wire can't ship into a parse path that's already broken — splitting the PRs would mean merging a no-op flag first.
  • Source: KD-0308

--limit validation — CLI rejects non-positive, backend owns the cap ​

  • Chose: CLI uses cobra's Int (rejects non-numeric) plus a > 0 pre-check; backend's min:1, max:500 rule is the single source of truth for the upper bound.
  • Rejected: Mirror the backend's 1..500 range in the CLI so every invalid value fails before the round-trip.
  • Why: Mirroring duplicates a canonical rule — if the backend ever raises the cap, a mirrored CLI silently caps low; the round-trip cost on --limit=600 is negligible and Laravel's error message is already user-friendly via parseAPIError.
  • Source: KD-0308

Truncation hint goes to stderr, not stdout ​

  • Chose: Write the "results truncated to N" footer to cmd.ErrOrStderr().
  • Rejected: Footer line on stdout under the table so it's always visible.
  • Why: Stdout footers pollute | jq / | grep pipelines; stderr stays visible in interactive use and invisible to pipes, which is the only way to be honest to humans without breaking scripts.
  • Source: KD-0308

--json stays a plain array, no envelope ​

  • Chose: --json output remains [{...}, {...}]; truncation info is stderr-only.
  • Rejected: Switch --json to {data: [...], meta: {...}} so programmatic consumers can see truncated.
  • Why: Wrapping breaks every existing kendo search --json | jq '.[0]' invocation; consumers who care about truncation can hit --limit exactly or read stderr.
  • Source: KD-0308

Omitted --limit sends no query param, lets backend default ​

  • Chose: When the user doesn't pass --limit, the CLI sends no limit= and the backend Action chooses the default.
  • Rejected: Send limit=500 (the backend max) so users get everything unless they opt in to less.
  • Why: "Sometimes" is the backend's declared shape for this param — owning the default in one place means a future backend tuning doesn't require a CLI release; opt-in maxing is a user choice, not a CLI policy.
  • Source: KD-0308

Label attach — dedicated issue label set, not --label on issue update ​

  • Chose: A dedicated kendo issue label set KD-42 bug,enhancement command hitting the label-sync endpoint (PUT /issues/{issue}/labels); issue update is not touched.
  • Rejected: A --label flag on issue update.
  • Why: A label-only issue update re-runs the full issue PUT, emitting a spurious "Issue Updated" audit row + broadcast event even when nothing but labels changed — the MCP sync-issue-labels tool deliberately avoids that side effect, and the CLI should not reintroduce it.
  • Source: KD-0830

issue create --label — accept it, two-call with pre-validation ​

  • Chose: issue create --label validates label IDs against the project first, creates the issue, then syncs labels (POST then PUT); a post-create sync failure prints a stderr warning but doesn't fail the command.
  • Rejected: No labels on create — force a separate issue label set afterward.
  • Why: It matches MCP create-issue (which accepts label_ids) so the two surfaces stay consistent; pre-validating label scope before the create means a bad label id never leaves a stray label-less issue behind, and the issue is genuinely created so failing the whole command on a sync hiccup would be misleading.
  • Source: KD-0830

search --label dropped — labels are project-scoped by design ​

  • Chose: Leave the global search command unmodified; project-scoped issue list --label covers label filtering.
  • Rejected: Add a project-scoped issue search command (or wire labels into global search) to satisfy the original AC4.
  • Why: The global search endpoint doesn't accept label_id[] because labels are project-scoped — the same boundary KD-0828 and KD-0829 drew — so honoring AC4 would need a backend change first and duplicate a capability issue list --label already provides.
  • Source: KD-0830