<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/1.x/2026-01-25-8-cli-first-command-interface/">
  <id>https://docs.spec-kitty.ai/adr/1.x/2026-01-25-8-cli-first-command-interface/</id>
  <title>CLI-First Command Interface</title>
  <updated>2026-01-25T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/1.x/2026-01-25-8-cli-first-command-interface/"/>
  <summary>Requires every command to be fully drivable by flags and environment, with prompting as an optional layer, so CI and headless containers never stall on input.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty commands currently mix interactive prompts with CLI flags. This makes
automation fragile and causes failures in non-TTY environments (CI, scripted
tests, headless containers). We need a consistent rule that every command can be
fully driven by CLI arguments without requiring interactive input, while still
allowing interactive UX when available.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;CI/CD and automated testing must be reliable and deterministic.&lt;/li&gt;
&lt;li&gt;Non-TTY environments cannot use keypress-based menus.&lt;/li&gt;
&lt;li&gt;Agents and scripts should not need to simulate interactive input.&lt;/li&gt;
&lt;li&gt;Interactive UX is still valuable for humans at the terminal.&lt;/li&gt;
&lt;li&gt;Command behavior should be explicit, discoverable, and documented.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; CLI-first for all commands with optional interactive mode&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Interactive-first with partial CLI overrides&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Separate interactive and non-interactive command variants&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Option 1: CLI-first for all commands with optional interactive mode”,
because it guarantees automation compatibility while preserving interactive UX.
Every command must be fully operable via flags/env without prompting.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;All commands become scriptable and CI-friendly.&lt;/li&gt;
&lt;li&gt;Automated tests avoid brittle input mocking.&lt;/li&gt;
&lt;li&gt;CLI help becomes a complete contract for command behavior.&lt;/li&gt;
&lt;li&gt;Interactive UX remains available for manual use.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;More flags/options to maintain and document.&lt;/li&gt;
&lt;li&gt;Additional validation logic to reconcile interactive vs non-interactive paths.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Interactive prompts are treated as a convenience layer over CLI defaults.&lt;/li&gt;
&lt;li&gt;Non-interactive mode may require explicit flags for safety.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We will validate this decision by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Ensuring every command has a complete CLI path with no required prompts.&lt;/li&gt;
&lt;li&gt;Maintaining CI tests that run commands in non-interactive mode.&lt;/li&gt;
&lt;li&gt;Auditing new commands for CLI completeness during review.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-cli-first-with-optional-interactive-mode&quot;&gt;Option 1: CLI-first with optional interactive mode&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Works in CI and automation by default&lt;/li&gt;
&lt;li&gt;Clear, testable command contract&lt;/li&gt;
&lt;li&gt;Keeps interactive UX for humans&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires more flags and documentation&lt;/li&gt;
&lt;li&gt;Slightly more implementation complexity&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-interactive-first-with-partial-cli-overrides&quot;&gt;Option 2: Interactive-first with partial CLI overrides&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Simpler UX for manual use&lt;/li&gt;
&lt;li&gt;Fewer flags to define initially&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Automation remains brittle&lt;/li&gt;
&lt;li&gt;Non-TTY environments fail without workarounds&lt;/li&gt;
&lt;li&gt;Inconsistent behavior across environments&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-separate-interactive-and-non-interactive-commands&quot;&gt;Option 3: Separate interactive and non-interactive commands&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Clear separation of concerns&lt;/li&gt;
&lt;li&gt;Simpler validation within each mode&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Duplicated commands and help text&lt;/li&gt;
&lt;li&gt;Users must learn two interfaces&lt;/li&gt;
&lt;li&gt;Increased maintenance surface&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Related implementation: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/init.py&lt;/code&gt; (non-interactive support)&lt;/li&gt;
&lt;li&gt;Docs: &lt;code dir=&quot;auto&quot;&gt;docs/how-to/non-interactive-init.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
