Skip to main content
Status: NON-NEGOTIABLE Constitutional PrincipleDefined in .aiox-core/constitution.md - All agents, tasks, and workflows MUST respect this principle. Violations are blocked automatically via gates.

​
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.

Core Tenet

Every feature MUST work 100% via CLI before any UI consideration. Dashboards observe; they never control or make decisions.

​
Constitutional Rules

From the AIOX Constitution v1.0.0:

​
MUST Rules

These rules are mandatory and enforced via automated gates:
1

CLI First Implementation

MUST: Toda funcionalidade nova DEVE funcionar 100% via CLI antes de qualquer UIEvery new feature must be fully functional through the command line before any user interface is considered.
2

Dashboard Observability Only

MUST: Dashboards apenas observam, NUNCA controlam ou tomam decisõesDashboards and UIs are read-only visualization layers. They cannot trigger actions, make decisions, or control system behavior.
3

UI Never Required

MUST: A UI NUNCA é requisito para operação do sistemaThe system must be fully operational without any graphical interface. CLI access is sufficient for all operations.
4

Implementation Priority

MUST: Ao decidir onde implementar, sempre CLI > Observability > UIWhen deciding where to implement functionality, always prioritize in this order:
  1. CLI (Primary)
  2. Observability/Metrics (Secondary)
  3. UI (Tertiary)

​
The Hierarchy

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

​
Why CLI First?

​
1. Automation & AI Integration

Agent-Friendly

AI agents operate through command-line interfaces. CLI-first design ensures agents have full system access without UI dependencies.
Example: 
# 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

Script Everything

CLI commands can be scripted, version-controlled, and executed reliably across environments.

Reproducible Workflows

Same commands produce same results every time, regardless of who or what executes them.

​
3. CI/CD Integration

Pipeline Native

Continuous Integration/Continuous Deployment pipelines operate via CLI. CLI-first ensures seamless integration.
GitHub Actions Example: 
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

Environment Agnostic

Servers, containers, and remote environments often lack graphical interfaces. CLI-first ensures functionality everywhere.
Use Cases:
  • Docker containers
  • SSH sessions
  • CI/CD runners
  • Cloud functions
  • Automated testing environments

​
5. Power & Precision

CLI provides:
  • Precise control over all parameters
  • Composability via pipes and scripting
  • Batch operations
  • Programmatic access
  • Complete feature surface

​
Gate Enforcement

Gate: dev-develop-story.md - WARN if UI created before CLI functional
The development workflow includes automated checks:
1

Feature Request

New functionality is proposed
2

CLI Implementation

Feature is implemented as CLI command(s) first
3

CLI Validation

Full testing via CLI to ensure completeness
4

Optional UI

Only after CLI is proven functional, UI may be considered

​
Practical Examples

​
Story Development

# 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

​
Quality Gates

# Automated quality checks
npm run lint
npm run typecheck
npm test
aiox devops pre-push-quality-gate

​
Agent Commands

Every agent command is CLI-accessible: 
# 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

​
Benefits in Practice

Agents can execute complete development cycles without human intervention:
# 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.
Complex workflows coordinating multiple agents:
# 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.
CLI provides precise control for recovery:
# 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.

​
Common Pitfalls

Anti-Pattern: Building UI before CLIResult:
  • Agents cannot automate
  • CI/CD cannot integrate
  • Manual intervention required
  • Reduced reliability
Anti-Pattern: Making UI control system behaviorResult:
  • Breaks automation
  • Creates dual control paths
  • Inconsistent behavior
  • Violates constitution
Best Practice: CLI → Test → Automate → Observe (optional UI)Result:
  • Full automation capability
  • Agent-friendly design
  • CI/CD native
  • Optional visualization

​
Integration with Other Principles

CLI First works in harmony with other constitutional principles:

Agent Authority

Agents execute their exclusive operations via CLI commands

Story-Driven Development

All development workflows are CLI-executable

Quality First

Quality gates run via CLI commands in automation

Workflows

All workflows are sequences of CLI commands

​
Verification

How to verify CLI First compliance:
1

Complete Feature Test

Can you execute the entire feature via CLI alone?✓ YES → Compliant
✗ NO → Violation
2

Agent Automation Test

Can an agent perform the operation without UI?✓ YES → Compliant
✗ NO → Violation
3

CI/CD Integration Test

Can the feature run in a headless CI/CD pipeline?✓ YES → Compliant
✗ NO → Violation
4

UI Dependency Test

If you remove all UI code, does the feature still work?✓ YES → Compliant
✗ NO → Violation

​
Summary

CLI First = Automation First

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.

​
Next Steps

Agent System

See how agents execute CLI commands

Workflows

Explore CLI-based workflow sequences

Getting Started

Start using AIOX CLI commands

Build docs developers (and LLMs) love

Get started for freeTalk to us