Elements CLI

The missing CLI for beautiful, interactive API docs powered by with Stoplight Elements

Installation

Install using npm as global package:

npm install -g @skriptfabrik/elements-cli

Usage

elements --help

Elements CLI

Usage:
  elements command [options] [arguments]

Options:
  -h, --help     Display this help message
  -v, --version  Print version number

Commands:
  export   Export rendered API docs
  preview  Preview rendered API docs

Export

elements export --help

Elements CLI

Usage:
  elements export [options] <openapi_json>

Arguments:
  openapi_json  The path or URL of the OpenAPI JSON file

Options:
      --base-path=BASE_PATH                    Use the given base path [default: "/"]
      --credentials-policy=CREDENTIALS_POLICY  Credentials policy for "Try It" feature: omit, include, same-origin [default: "omit"]
      --cors-proxy=CORS_PROXY                  Provide CORS proxy
  -f, --filter-internal                        Filter out any content which has been marked as internal with x-internal
  -h, --help                                   Display this help message
      --layout=LAYOUT                          Layout for Elements: sidebar, stacked [default: "sidebar"]
      --logo=LOGO                              URL of an image that will show as a small square logo next to the title
  -n  --no-try-it                              Hide the "Try It" panel (the interactive API console)
      --router=ROUTER                          Determines how navigation should work: history, hash, memory, static [default: "history"]
      --style=STYLE                            Additional style for Elements [default: "flex: 1 0 0; overflow: hidden;"]
      --title=TITLE                            API docs title [default: "My API Docs"]
      --variable=VARIABLE                      Variable to be replaced in the OpenAPI document
  -v, --version                                Print version number

Examples:
  Export rendered API docs based on local openapi.json path as index.html:

    elements export openapi.json > index.html

  Export rendered Swagger Petstore docs based on remote https://petstore.swagger.io/v2/swagger.json URL as index.html:

    elements export --title="Swagger Petstore" https://petstore.swagger.io/v2/swagger.json > index.html

Preview

elements preview --help

Elements CLI

Usage:
  elements preview [options] <openapi_json>

Arguments:
  openapi_json  The path or URL of the OpenAPI JSON file

Options:
      --base-path=BASE_PATH                    Use the given base path [default: "/"]
      --credentials-policy=CREDENTIALS_POLICY  Credentials policy for "Try It" feature: omit, include, same-origin [default: "omit"]
  -c  --with-cors-proxy                        Enable CORS proxy capabilities
  -f, --filter-internal                        Filter out any content which has been marked as internal with x-internal
  -h, --help                                   Display this help message
      --hostname=HOSTNAME                      Server hostname [default: "localhost"]
      --layout=LAYOUT                          Layout for Elements: sidebar, stacked [default: "sidebar"]
      --logo=LOGO                              URL of an image that will show as a small square logo next to the title
  -n  --no-try-it                              Hide the "Try It" panel (the interactive API console)
  -p, --poll                                   Use polling instead of file system events
      --port=PORT                              Server port [default: 8000]
      --router=ROUTER                          Determines how navigation should work: history, hash, memory, static [default: "history"]
      --style=STYLE                            Additional style for Elements [default: "flex: 1 0 0; overflow: hidden;"]
      --title=TITLE                            API docs title [default: "My API Docs"]
      --variable=VARIABLE                      Variable to be replaced in the OpenAPI document
  -v, --version                                Print version number
  -w  --watch                                  Watch for changes and reload (only for local files)
      --virtual-host=VIRTUAL_HOST              Reported hostname [default: localhost]
      --virtual-port=VIRTUAL_PORT              Reported port [default: 8000]
      --working-dir=PWD                        Use the given directory as working directory

Examples:
  Preview rendered API docs based on local openapi.json path:

    elements preview openapi.json

  Preview rendered Swagger Petstore docs based on remote https://petstore.swagger.io/v2/swagger.json URL:

    elements preview --title="Swagger Petstore" https://petstore.swagger.io/v2/swagger.json

  Preview local API docs, enable CORS proxy and watch/reload on data changes:

    elements preview -cw openapi.json

Docker

Export

Export rendered Swagger Petstore docs as index.html:

docker run --rm skriptfabrik/elements-cli export --title="Swagger Petstore" https://petstore.swagger.io/v2/swagger.json > index.html

Preview

Use the following command to preview rendered API docs at http://localhost:8080/ based on mounted openapi.json path:

docker run --rm -p 8000:8000 -v `pwd`:/data:ro skriptfabrik/elements-cli preview openapi.json

Preview rendered Swagger Petstore docs at http://localhost:8080/ based on remote URL:

docker run --rm -p 8000:8000 skriptfabrik/elements-cli preview --title="Swagger Petstore" https://petstore.swagger.io/v2/swagger.json

Preview mounted API docs at http://localhost:8080/, enable CORS proxy capabilities and watch/reload on data changes:

docker run --rm -p 8000:8000 -v `pwd`:/data:ro skriptfabrik/elements-cli preview -cw openapi.json