# CLI Specification

> Generated by openlore on 2025-01-30
> Source files: src/commands/spec.ts, src/commands/change.ts, src/commands/validate.ts, src/commands/schema.ts

## Purpose

Provides command-line interface for managing OpenSpec projects, including spec viewing, change management, validation, and schema inspection. Supports both interactive and non-interactive modes with multiple output formats.

## Entities

### CommandOptions

| Property | Type | Description |
|----------|------|-------------|
| json | boolean | Output as JSON instead of formatted text |
| noInteractive | boolean | Disable interactive prompts |
| verbose | boolean | Enable detailed output |
| all | boolean | Apply to all items |

### OutputFormat

| Value | Description |
|-------|-------------|
| text | Human-readable formatted markdown |
| json | Machine-readable JSON structure |

## Requirements

### Requirement: SpecViewing

The system SHALL display spec content in human-readable or JSON format.

#### Scenario: ViewSpecAsMarkdown
- **GIVEN** a valid spec file at `openspec/specs/user/spec.md`
- **WHEN** the user runs `openspec show specs/user`
- **THEN** the spec content is displayed with formatted markdown

#### Scenario: ViewSpecAsJSON
- **GIVEN** a valid spec file
- **WHEN** the user runs `openspec show specs/user --json`
- **THEN** the spec is output as a JSON object
- **AND** the JSON includes parsed requirements and scenarios

### Requirement: SpecListing

The system SHALL list all specs in the project with summary information.

#### Scenario: ListAllSpecs
- **GIVEN** a project with 5 spec files
- **WHEN** the user runs `openspec list --specs`
- **THEN** all 5 specs are listed with names and paths

### Requirement: ChangeManagement

The system SHALL support creating, listing, and viewing changes.

#### Scenario: CreateNewChange
- **GIVEN** an initialized OpenSpec project
- **WHEN** the user runs `openspec change my-feature`
- **THEN** a directory `openspec/changes/my-feature/` is created
- **AND** template files (proposal.md, etc.) are generated

#### Scenario: ListActiveChanges
- **GIVEN** a project with 3 active changes
- **WHEN** the user runs `openspec list --changes`
- **THEN** all 3 changes are listed with status information

### Requirement: BulkValidation

The system SHALL validate multiple specs/changes concurrently with configurable parallelism.

#### Scenario: ValidateAllSpecs
- **GIVEN** a project with 10 spec files
- **WHEN** the user runs `openspec validate --all`
- **THEN** all specs are validated
- **AND** a summary report shows pass/fail counts

#### Scenario: ValidationWithConcurrency
- **GIVEN** 20 spec files to validate
- **WHEN** validation runs with default concurrency
- **THEN** multiple files are validated in parallel
- **AND** total validation time is reduced

### Requirement: InteractivePrompts

The system SHALL prompt for missing required arguments when in interactive mode.

#### Scenario: MissingSpecIdPrompt
- **GIVEN** the user runs `openspec show` without specifying a spec
- **WHEN** interactive mode is enabled (default)
- **THEN** a prompt lists available specs for selection

#### Scenario: NonInteractiveFailure
- **GIVEN** the user runs `openspec show --no-interactive` without a spec
- **WHEN** the command executes
- **THEN** an error is returned indicating missing required argument

### Requirement: SchemaInspection

The system SHALL allow inspection of workflow schemas including artifact dependencies.

#### Scenario: ListSchemas
- **GIVEN** schemas in project, user, and package locations
- **WHEN** the user runs `openspec schema list`
- **THEN** all available schemas are listed with source location

#### Scenario: ShowSchemaDetails
- **GIVEN** a schema named "spec-driven"
- **WHEN** the user runs `openspec schema show spec-driven`
- **THEN** the schema artifacts and dependencies are displayed

#### Scenario: ValidateSchemaGraph
- **GIVEN** a schema with artifact dependencies
- **WHEN** the user runs `openspec schema validate spec-driven`
- **THEN** cycle detection is performed
- **AND** dependency graph is validated

### Requirement: OutputFormatting

The system SHALL support multiple output formats for different use cases.

#### Scenario: ColoredTerminalOutput
- **GIVEN** a TTY terminal environment
- **WHEN** commands produce output
- **THEN** colors and formatting enhance readability

#### Scenario: PlainTextForPipes
- **GIVEN** output is piped to another command
- **WHEN** commands produce output
- **THEN** ANSI codes are stripped
- **AND** plain text is output

## Technical Notes

- **Implementation**: `src/commands/spec.ts`, `src/commands/change.ts`, `src/commands/validate.ts`
- **Framework**: Commander.js for command parsing, Inquirer for prompts
- **Dependencies**: validation, parsing