RFC: Framna Docs CLI

[ulrikandersen]

RFC: Framna Docs CLI

Overview

Command-line interface for browsing OpenAPI documentation hosted on Framna Docs. Authenticates via GitHub and provides read-only access to projects, endpoints, and schemas.

Authentication

framna-docs auth login    # Authenticate via browser
framna-docs auth status   # Check session
framna-docs auth logout   # Clear session

Command Structure

framna-docs
├── auth
│   ├── login
│   ├── logout
│   └── status
├── projects
│   ├── list                    # List all accessible projects
│   └── get <owner/name>        # Get project details (versions, specs)
├── endpoints
│   ├── list                    # List all endpoints
│   ├── search <query>          # Search by path/summary/operationId
│   └── get <path> <method>     # Get endpoint with params, responses, schemas
├── schemas
│   ├── list                    # List all schemas
│   └── get <name>              # Get schema definition
├── spec                        # Get full OpenAPI spec
└── cache
    ├── status
    └── clear

Common Options

Flag	Description
-p, --project <owner/name>	Target project
-a, --at <version>	Version reference (branch, tag)*
-s, --spec <spec>	Spec filename
--json	JSON output
--yaml	YAML output

* -a, --at is used because -v and --version are reserved for CLI version output.

Usage Examples

# Discover available projects
framna-docs projects list

# Inspect a project's structure
framna-docs projects get shapehq/plus

# Browse endpoints
framna-docs endpoints list -p shapehq/plus -a main -s openapi.yml
framna-docs endpoints search "payment" -p shapehq/plus -a main -s openapi.yml
framna-docs endpoints get "/payments/{id}" get -p shapehq/plus -a main -s openapi.yml

# Inspect schemas
framna-docs schemas list -p shapehq/plus -a main -s openapi.yml
framna-docs schemas get PaymentRequest -p shapehq/plus -a main -s openapi.yml

# Export full spec
framna-docs spec -p shapehq/plus -a main -s openapi.yml --yaml > api.yml

Output

• Human-readable tables by default
• --json / --yaml for scripting and piping
• Errors exit with code 1