CLI Reference

run

Optic's CI workflow command, optic run, tests that every OpenAPI specification in your repo is accurate, has no breaking changes and follows the standards you defined in the optic.yml file; then posts a comment with a report to your PR/MR and exits with code 1 when issues are found.

Usage

> optic run

Arguments

file_paths   OpenAPI specification files to handle, comma separated globs.
             Leave empty to let Optic detect files.

Options

--ignore <ignore-glob>  OpenAPI specification files to ignore, comma separated globs.
--include-git-ignored   Set to true to also match Git ignored files. (default: false)
--severity <severity>   Use `none` to prevent Optic from exiting 1 when
                        issues are found. (choices: "none", "error", default: "error")

diff

optic diff runs a diff against two OpenAPI specs. Run this command to see the changes between OpenAPI spec versions. Include the --check flag if you also want to check for change based rules (e.g. breaking changes).

ℹ️

You can configure rules by adding an optic.yml file at the root of your repo. Learn about standards to see what else you can check for.

Usage

> optic diff <openapi-file> --base <base> [options] # diff against a git ref
> optic diff <openapi-file> <openapi-file-to-compare-against> [options] # diff two files

Arguments

openapi-file                        an OpenAPI spec file to diff. Can be a path to a file or a git ref (e.g. ./spec.yml or main:spec.yml)
openapi-file-to-compare-against     an OpenAPI spec file to diff against

Options

--base <base>              the base ref to compare against. Defaults to HEAD. Also supports optic
                            cloud tags (cloud:tag_name) (default: "HEAD")
--standard <standard>      run comparison with a locally defined standard, if not set, looks for
                            the standard on the [x-optic-standard] key on the spec, and then the
                            optic.dev.yml file.
--head-tag <head-tag>      Adds additional tags to the HEAD spec. Should be used in conjunction
                            with `--upload`
--severity <severity>      specify the severity level to exit with exit code, options are error,
                            warn and info (choices: "error", "warn", "info", default: "error")
--validation <validation>  specify the level of validation to run (choices: "strict", "loose",
                            default: "strict")
--check                    enable checks (default: false)
--upload                   upload run to cloud (default: false)
--web                      view the diff in the optic changelog web view (default: false)
--json                     output as json (default: false)
--generated                use with --upload with a generated spec (default: false)
--last-change              find the last change for this spec (default: false)

Example

> optic diff openapi-spec.yml --base master --check
 
GET /store/order/{orderId}:
  - response 200:
    - body application/json:
      - /schema/properties/summary added
      - /schema/properties/status changed
 
POST /store/order:
  - request:
    - body */*:
      - /schema/properties/summary added
      - /schema/properties/status changed
 
  - response 200:
    - body application/json:
      - /schema/properties/summary added
      - /schema/properties/status changed
 
Checks
 
   PASS  GET /store/order/{orderId}
 
   PASS  POST /store/order
 
7 operations added, 9 changed
10 passed
0 errors

capture

The capture command starts a proxy, runs your tests (or other commands), and analyzes traffic that passes though the proxy. Optic uses data about the requests it observes to update your OpenAPI specification accordingly. Capture's behavior is determined by the capture block in your optic.yml file. For a complete set of configuration options, see the configuration reference.

ℹ️

By default, Optic will capture requests but not persist them to your OpenAPI spec. Create or update your OpenAPI spec by including the --update <mode> option documented below.

Usage

> optic capture [options] [command] <openapi-file> [target-url]

Arguments

openapi-file                          an OpenAPI spec file to add an operation to
target-url                            the url to capture (deprecated, use optic.yml configuration instead)

Options

--proxy-port <proxy-port>             specify the port the proxy should be running on
-u, --update [mode]                   update the OpenAPI spec to match the traffic. specify the mode to change the update
                                      behavior on how to handle undocumented endpoints (endpoints not in your spec).
                                      documented will only update documented endpoints. interactive will prompt you for new
                                      endpoint paths. automatic will guess the correct path (choices: "interactive",
                                      "automatic", "documented", preset: "documented")
--postman  <postman-collection-file>  path to postman collection
--har <har-file, directory>           path to har file (v1.2, v1.3), or directory containing har files
--verbose                             display verbose diff output (default: false)
-s, --server-override <url>           Skip executing `capture[].server.command` and forward proxy traffic to this URL instead
--upload                              upload coverage results to Optic Cloud (default: false)
-h, --help                            display help for command

capture clear

optic capture clear clears any saved capture data.

Usage

> optic capture clear [options] [openapi-file]

Options

--all         clear all captured traffic
-h, --help    display help for command

capture init

optic capture init displays a complete, commented, capture configuration block or write it to Optic.yml.

Usage

> optic capture init [options] <openapi-file>

Options

--stdout      Print the capture config to stdout instead of writing to optic.yml (default: false)
-h, --help    display help for command

login

optic login interactively logs the CLI into Optic Cloud.

> optic login

Example

> optic login
Generate a token below
 
Create an account and generate a personal access token at https://app.useoptic.com/user-settings/personal-access-token/new
 
 
✔ Enter your token here: … ***********************************************************************************************************
 
Verifying your token
Successfully saved your personal access token to /Users/user/.config/optic/config.json

history

Browse an OpenAPI specification file history and create a changelog in markdown format.

Usage

> optic history <path_to_spec.yml> > changelog.md

> cat changelog.md
 
# Swagger Petstore
### Sun Jan 01 2023
- \`PUT\` \`/user/{username}\`:
- removed \`requestBody\` \`phone\` property
- added \`requestBody\` \`bio\` property
- changed \`requestBody\` \`userStatus\`.\`type\`

Options

-D, --history-depth <history-depth>  Sets the depth of how far to crawl through to historic API data. history-depth=0 will crawl the entire history (default: "0")

Rails Sinatra Rack CLI Configuration Reference