> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI First

> The foundational principle: CLI is the source of truth for all intelligence and automation

<Note>
  **Status**: NON-NEGOTIABLE Constitutional Principle

  Defined in `.aiox-core/constitution.md` - All agents, tasks, and workflows MUST respect this principle. Violations are blocked automatically via gates.
</Note>

## The Principle

The CLI (Command Line Interface) is the **source of truth** where all intelligence, execution, and automation reside. This is not a preference—it's an architectural imperative.

<Card title="Core Tenet" icon="gavel">
  Every feature MUST work 100% via CLI before any UI consideration. Dashboards observe; they never control or make decisions.
</Card>

## Constitutional Rules

From the AIOX Constitution v1.0.0:

### MUST Rules

<Warning>
  These rules are **mandatory** and enforced via automated gates:
</Warning>

<Steps>
  <Step title="CLI First Implementation">
    **MUST**: Toda funcionalidade nova DEVE funcionar 100% via CLI antes de qualquer UI

    Every new feature must be fully functional through the command line before any user interface is considered.
  </Step>

  <Step title="Dashboard Observability Only">
    **MUST**: Dashboards apenas observam, NUNCA controlam ou tomam decisões

    Dashboards and UIs are **read-only visualization layers**. They cannot trigger actions, make decisions, or control system behavior.
  </Step>

  <Step title="UI Never Required">
    **MUST**: A UI NUNCA é requisito para operação do sistema

    The system must be fully operational without any graphical interface. CLI access is sufficient for all operations.
  </Step>

  <Step title="Implementation Priority">
    **MUST**: Ao decidir onde implementar, sempre CLI > Observability > UI

    When deciding where to implement functionality, always prioritize in this order:

    1. CLI (Primary)
    2. Observability/Metrics (Secondary)
    3. UI (Tertiary)
  </Step>
</Steps>

## The Hierarchy

```mermaid theme={null}
graph TD
    A[CLI - Primary] --> B[Observability - Secondary]
    B --> C[UI - Tertiary]
    
    A:::primary
    B:::secondary
    C:::tertiary
    
    classDef primary fill:#1a73e8,color:#fff,stroke:#1a73e8,stroke-width:4px
    classDef secondary fill:#f9ab00,color:#fff,stroke:#f9ab00,stroke-width:3px
    classDef tertiary fill:#34a853,color:#fff,stroke:#34a853,stroke-width:2px
```

<Tabs>
  <Tab title="CLI (Primary)">
    **Maximum Authority**

    * All core functionality implemented here
    * Complete access to all system capabilities
    * Source of truth for automation
    * Where agents execute commands
    * Where workflows are orchestrated

    **Examples:**

    * `aiox dev develop story-1.2.3`
    * `aiox qa review story-1.2.3`
    * `aiox devops push`
  </Tab>

  <Tab title="Observability (Secondary)">
    **Metrics & Monitoring**

    * System health metrics
    * Performance monitoring
    * Build status tracking
    * Agent activity logs
    * Workflow progress indicators

    **Purpose:** Visibility into system state, NOT control
  </Tab>

  <Tab title="UI (Tertiary)">
    **Optional Visualization**

    * Read-only dashboards
    * Progress visualization
    * Report generation
    * Data exploration

    **Purpose:** Human-friendly views of data, NOT system control

    <Warning>
      UI cannot:

      * Trigger builds
      * Approve stories
      * Deploy code
      * Modify system state
    </Warning>
  </Tab>
</Tabs>

## Why CLI First?

### 1. Automation & AI Integration

<Card title="Agent-Friendly" icon="robot">
  AI agents operate through command-line interfaces. CLI-first design ensures agents have full system access without UI dependencies.
</Card>

**Example:**

```bash theme={null}
# Agent can execute complete workflow via CLI
aiox sm draft story-1.2.3
aiox po validate-story-draft story-1.2.3
aiox dev develop-yolo story-1.2.3
aiox qa review story-1.2.3
aiox devops push
```

No UI required. No mouse clicks. Pure automation.

### 2. Scriptability & Reproducibility

<CardGroup cols={2}>
  <Card title="Script Everything" icon="code">
    CLI commands can be scripted, version-controlled, and executed reliably across environments.
  </Card>

  <Card title="Reproducible Workflows" icon="repeat">
    Same commands produce same results every time, regardless of who or what executes them.
  </Card>
</CardGroup>

### 3. CI/CD Integration

<Card title="Pipeline Native" icon="pipe">
  Continuous Integration/Continuous Deployment pipelines operate via CLI. CLI-first ensures seamless integration.
</Card>

**GitHub Actions Example:**

```yaml theme={null}
steps:
  - name: Run Quality Gate
    run: aiox qa gate story-${{ github.event.number }}
    
  - name: Execute Pre-Push Checks
    run: aiox devops pre-push-quality-gate
```

### 4. Remote & Headless Environments

<Card title="Environment Agnostic" icon="server">
  Servers, containers, and remote environments often lack graphical interfaces. CLI-first ensures functionality everywhere.
</Card>

**Use Cases:**

* Docker containers
* SSH sessions
* CI/CD runners
* Cloud functions
* Automated testing environments

### 5. Power & Precision

<Check>
  **CLI provides:**

  * Precise control over all parameters
  * Composability via pipes and scripting
  * Batch operations
  * Programmatic access
  * Complete feature surface
</Check>

## Gate Enforcement

<Warning>
  **Gate**: `dev-develop-story.md` - WARN if UI created before CLI functional
</Warning>

The development workflow includes automated checks:

```mermaid theme={null}
graph LR
    A[New Feature] --> B{CLI Complete?}
    B -->|No| C[BLOCK: Implement CLI First]
    B -->|Yes| D{UI Requested?}
    D -->|Yes| E[WARN: Verify CLI Priority]
    D -->|No| F[APPROVE: Proceed]
    E --> F
    
    style C fill:#dc3545,color:#fff
    style E fill:#f9ab00,color:#fff
    style F fill:#34a853,color:#fff
```

<Steps>
  <Step title="Feature Request">
    New functionality is proposed
  </Step>

  <Step title="CLI Implementation">
    Feature is implemented as CLI command(s) first
  </Step>

  <Step title="CLI Validation">
    Full testing via CLI to ensure completeness
  </Step>

  <Step title="Optional UI">
    Only after CLI is proven functional, UI may be considered
  </Step>
</Steps>

## Practical Examples

### Story Development

<CodeGroup>
  ```bash CLI (Correct) theme={null}
  # Complete story workflow via CLI
  aiox sm draft
  aiox dev develop story-1.2.3
  aiox qa review story-1.2.3
  aiox devops push
  ```

  ```bash UI (Wrong) theme={null}
  # ❌ Cannot do via UI click
  # UI only shows status
  # Cannot trigger development
  # Cannot approve stories
  # Cannot push code
  ```
</CodeGroup>

### Quality Gates

<CodeGroup>
  ```bash CLI (Correct) theme={null}
  # Automated quality checks
  npm run lint
  npm run typecheck
  npm test
  aiox devops pre-push-quality-gate
  ```

  ```bash UI Dashboard (Observation Only) theme={null}
  # ✓ View test results
  # ✓ See lint errors
  # ✓ Monitor build status
  # ✗ Cannot trigger tests
  # ✗ Cannot bypass gates
  # ✗ Cannot approve builds
  ```
</CodeGroup>

### Agent Commands

Every agent command is CLI-accessible:

<Tabs>
  <Tab title="Developer Agent">
    ```bash theme={null}
    # Story implementation
    aiox dev develop story-1.2.3
    aiox dev develop-yolo story-1.2.3
    aiox dev run-tests
    aiox dev apply-qa-fixes
    ```
  </Tab>

  <Tab title="QA Agent">
    ```bash theme={null}
    # Quality assurance
    aiox qa review story-1.2.3
    aiox qa gate story-1.2.3
    aiox qa backlog-debt
    ```
  </Tab>

  <Tab title="DevOps Agent">
    ```bash theme={null}
    # Deployment operations
    aiox devops pre-push-quality-gate
    aiox devops push
    aiox devops github-pr-automation
    ```
  </Tab>
</Tabs>

## Benefits in Practice

<AccordionGroup>
  <Accordion title="Autonomous Agent Workflows">
    Agents can execute complete development cycles without human intervention:

    ```bash theme={null}
    # Fully autonomous story implementation
    aiox dev build-autonomous story-1.2.3
    ```

    This single command:

    * Creates isolated worktree
    * Plans implementation
    * Executes all subtasks
    * Runs verification
    * Handles failures with retries
    * Merges when complete

    **Impossible with UI-first design.**
  </Accordion>

  <Accordion title="Multi-Agent Orchestration">
    Complex workflows coordinating multiple agents:

    ```bash theme={null}
    # PM orchestrates entire epic
    aiox pm execute-epic epic-5.1
    ```

    Behind the scenes:

    * PM assigns executors
    * SM validates stories
    * Dev implements
    * QA reviews
    * DevOps deploys

    All via CLI commands, scriptable and repeatable.
  </Accordion>

  <Accordion title="Recovery & Debugging">
    CLI provides precise control for recovery:

    ```bash theme={null}
    # Check build status
    aiox dev build-status --all

    # Resume failed build
    aiox dev build-resume story-1.2.3

    # Rollback if needed
    aiox dev rollback --hard
    ```

    UI dashboards show status; CLI executes fixes.
  </Accordion>
</AccordionGroup>

## Common Pitfalls

<Warning>
  **Anti-Pattern**: Building UI before CLI

  **Result**:

  * Agents cannot automate
  * CI/CD cannot integrate
  * Manual intervention required
  * Reduced reliability
</Warning>

<Warning>
  **Anti-Pattern**: Making UI control system behavior

  **Result**:

  * Breaks automation
  * Creates dual control paths
  * Inconsistent behavior
  * Violates constitution
</Warning>

<Check>
  **Best Practice**: CLI → Test → Automate → Observe (optional UI)

  **Result**:

  * Full automation capability
  * Agent-friendly design
  * CI/CD native
  * Optional visualization
</Check>

## Integration with Other Principles

CLI First works in harmony with other constitutional principles:

<CardGroup cols={2}>
  <Card title="Agent Authority" icon="user-shield" href="/concepts/agents#authority">
    Agents execute their exclusive operations via CLI commands
  </Card>

  <Card title="Story-Driven Development" icon="book" href="/concepts/story-driven-development">
    All development workflows are CLI-executable
  </Card>

  <Card title="Quality First" icon="shield-check" href="/guides/quality-gates">
    Quality gates run via CLI commands in automation
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/concepts/workflows">
    All workflows are sequences of CLI commands
  </Card>
</CardGroup>

## Verification

How to verify CLI First compliance:

<Steps>
  <Step title="Complete Feature Test">
    Can you execute the entire feature via CLI alone?

    ✓ YES → Compliant\
    ✗ NO → Violation
  </Step>

  <Step title="Agent Automation Test">
    Can an agent perform the operation without UI?

    ✓ YES → Compliant\
    ✗ NO → Violation
  </Step>

  <Step title="CI/CD Integration Test">
    Can the feature run in a headless CI/CD pipeline?

    ✓ YES → Compliant\
    ✗ NO → Violation
  </Step>

  <Step title="UI Dependency Test">
    If you remove all UI code, does the feature still work?

    ✓ YES → Compliant\
    ✗ NO → Violation
  </Step>
</Steps>

## Summary

<Card title="CLI First = Automation First" icon="bolt">
  By making CLI the primary interface, AIOX ensures:

  * Full agent automation capability
  * Scriptable, repeatable workflows
  * CI/CD native integration
  * Environment independence
  * Power user efficiency

  **The UI is optional. The CLI is essential.**
</Card>

## Next Steps

<CardGroup cols={3}>
  <Card title="Agent System" icon="robot" href="/concepts/agents">
    See how agents execute CLI commands
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/concepts/workflows">
    Explore CLI-based workflow sequences
  </Card>

  <Card title="Getting Started" icon="rocket" href="/quickstart">
    Start using AIOX CLI commands
  </Card>
</CardGroup>