Why not openapi?

[mpsanchis]

Hi Jeff!

A colleague and I were discussing CLI specs some time ago, and we thought of reusing openapi for CLI. It would just need a re-interpretation of the fields.

Path params would be commands:

mycli/generate/resource

would become:

mycli generate resource

And query params would be flags:

mycli/generate/resource?dry-run=true&verbose=true

would become:

mycli generate resource --dry-run=true --verbose=true

My guess is that probably you saw some limitations of this. Maybe we were thinking only of very simple CLIs.

Could you share these thoughts? Or maybe you already wrote it somewhere and I missed it.

Thanks!

[mpsanchis]

Adding an example to explain myself better:

openapi: 3.0.0
info:
  title: Cool CLI API
  version: 1.0.0
  description: >
    An OpenAPI 3.1.0 spec modeling the Codeak terminal CLI. 
    Commands are modeled as paths, flags as query parameters.
    Global and command-specific flags are included.

components:
  parameters:
    LogLevel:
      name: logLevel
      in: query
      required: false
      description: Log verbosity level
      schema:
        type: string
        enum: [debug, info, error]

    Parallel:
      name: parallel
      in: query
      required: false
      description: Number of parallel operations
      schema:
        type: integer
        minimum: 1

    OutputFormat:
      name: outputFormat
      in: query
      required: false
      description: Output format
      schema:
        type: string
        enum: [json, yaml]

    DryRun:
      name: dryRun
      in: query
      required: false
      description: Simulate the command without making changes
      schema:
        type: boolean
    
    Help:
      name: help
      in: query
      required: false
      description: Get help for a command
      schema:
        type: boolean

paths:
  /login:
    get:
      summary: Log in to Platform
      parameters:
        - name: u
          in: query
          required: true
          description: Username
          schema:
            type: string
        - name: p
          in: query
          required: true
          description: Password
          schema:
            type: string
        - $ref: '#/components/parameters/LogLevel'
        - $ref: '#/components/parameters/Parallel'
        - $ref: '#/components/parameters/OutputFormat'
      responses:
        '200':
          description: Successful login
        '401':
          description: Invalid credentials

  /forge/build/{path}:
    get:
      summary: Build a project using Forge
      description: >
        Alias: `cool build` (same as `cool forge build`)
      parameters:
        - name: path
          in: path
          required: true
          description: Path to the project (can include `**` wildcard)
          schema:
            type: string
        - $ref: '#/components/parameters/DryRun'
        - $ref: '#/components/parameters/LogLevel'
        - $ref: '#/components/parameters/Parallel'
        - $ref: '#/components/parameters/OutputFormat'
      responses:
        '200':
          description: Build started
        '400':
          description: Invalid path provided

  /version:
    get:
      summary: Show CLI version
      description: Equivalent to `cool --version`
      responses:
        '200':
          description: Version info returned

[jbadeau]

We could even render a different ui to make it easier to read and test