Make tkn CLI agent-friendly for AI/LLM consumption

[vdemeester]

Summary

AI agents are increasingly using CLIs as their primary interface to external systems. The tkn CLI should be optimized for both human and agent consumption, following principles from You Need to Rewrite Your CLI for AI Agents.

Motivation

AI coding agents (Copilot, Claude Code, Cursor, etc.) use CLIs directly. They need:

• Deterministic, machine-readable output — not tables designed for human eyes
• Self-describing conventions — agents need to know how to use the CLI efficiently
• Structured input — agents generate JSON more reliably than bespoke flag combinations
• Reliable exit codes — agents depend on exit codes, not output parsing

Currently, tkn has inconsistent --output support, no non-TTY auto-detection, undocumented exit codes, and no structured JSON input path.

Sub-issues

Ordered by priority / effort-to-value ratio:

Phase 1 — Foundations

1. Ship a CONTEXT.md for AI agent consumption #2856 — Ship a CONTEXT.md for AI agents (zero code, highest ROI)
2. Add consistent --output json support to all tkn commands #2850 — Consistent --output json on all commands + non-TTY auto-detection
3. Define consistent exit codes for all tkn commands #2855 — Consistent, documented exit codes

Phase 2 — Enhanced agent support

4. Support structured JSON input for start commands #2851 — Structured JSON input for start commands
5. Add field selection and NDJSON streaming for list commands #2853 — Field selection (--fields) — client-side filtering to reduce agent token consumption
6. Make pipelinerun/taskrun logs agent-friendly #2854 — Agent-friendly logs output (structured NDJSON logs)

Phase 3 — Advanced capabilities

7. Adversarial input validation for agent-generated commands #2859 — Adversarial input validation for agent-generated commands
8. Add schema introspection command (tkn schema) #2852 — Runtime schema introspection for agent discovery
9. Dry-run and validation for mutating operations #2860 — Dry-run and validation for mutating operations
10. MCP surface for tkn CLI #2861 — MCP surface for direct agent integration

References

• You Need to Rewrite Your CLI for AI Agents — Justin Poehnelt (Google)
• The MCP Abstraction Tax — followup on protocol layers