Skip to content
XMachines

RFC: CLI (v1)

Status: Draft
Version: v1
Scope: Command-line interface architecture, configuration, and implementation resolution
Non-goals: Execution semantics, protocol definitions, stream behavior

1. Purpose

This RFC defines the XMachines CLI architecture.

The CLI provides:

  • a human-facing interface to XMachines capabilities
  • configuration and defaults for implementation selection
  • an orchestration layer over RFC-defined capabilities

The CLI does not define behavior. It selects and wires implementations.

2. Design Principles

  1. CLI is optional
  2. CLI never defines semantics
  3. CLI resolves implementations explicitly
  4. Configuration is explicit and persistent
  5. Alias packages expose commands, implementation packages implement behavior

3. Package Structure

  • @xmachines/cli
  • built using oclif
  • contains command definitions and shared helpers only

4. Implementation Resolution

Resolution order:

  1. explicit CLI flags
  2. persisted configuration
  3. alias-level defaults (if any)
  4. error

Implementation identifiers are stored as fully qualified package names. If no scope is provided, default scope is @xmachines/.

5. Configuration Model

  • stored via oclif config
  • user-scoped
  • persistent across upgrades

Defaults follow a first-writer-wins strategy.

6. Install & Uninstall Hooks

Implementation packages MAY:

  • suggest themselves as defaults on install
  • respect if-not-set or quiet strategies
  • avoid auto-reassignment on uninstall

Uninstall MAY support an explicit purge option to remove config entries.

7. Feature Enablement

Some capabilities expose features (e.g. REST, Git, MCP).

Rules:

  • features map to installed packages
  • enablement is explicit
  • disablement requires explicit flags

8. Scope Boundaries

The CLI:

  • wires components
  • launches servers
  • manages configuration

The CLI does NOT:

  • define protocol semantics
  • parse stream payloads
  • implement execution logic

9. Invariants

  1. No implicit defaults
  2. Explicit implementation selection
  3. CLI never defines semantics

10. Lock statement

The CLI is an orchestration and configuration layer only.
All semantics live in other RFCs.
This is CLI v1.