Docs
CLI Reference

CLI Reference

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

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

diff-all (deprecated. use optic run)

optic diff-all runs diffs on all OpenAPI specs in your current working directory or in the current git repository. 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.

⚠️

optic diff-all when run in a git repository will respect the .gitignore file. If you have files you want to diff that are being ignored, use the --match option.

Usage

> optic diff-all [options]

Options

  --compare-to <compare-to>      the head ref to compare against. Defaults to the current working
                                 directory
  --compare-from <compare-from>  the base ref to compare against. Defaults to HEAD~1. Also supports
                                 optic cloud tags (cloud:tag_name) (default: "HEAD~1")
  --head-tag <head-tag>          Adds additional tags to the HEAD spec. Should be used in
                                 conjunction with `--upload`
  --match <match>                a glob to match specs (e.g. "**/*.yml" or
                                 "**/specifications/*.json"). Also takes       comma separated
                                 values (e.g. "**/*.yml,**/*.json")
  --ignore <ignore>              an ignore glob to ignore certain matches (e.g. "**/*.yml" or
                                 "**/specifications/*.json"). Also takes comma separated values
                                 (e.g. "**/*.yml,**/*.json")
  --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.
  --validation <validation>      specify the level of validation on HEAD specs (choices: "strict",
                                 "loose", default: "strict")
  --severity <severity>          specify the severity level to exit with exit code, options are
                                 error, warn and info (choices: "error", "warn", "info", default:
                                 "error")
  --check                        enable checks (default: false)
  --upload                       upload specs (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)
  --fail-on-untracked-openapi    fail with exit code 1 if there are detected untracked apis
                                 (default: false)

capture

optic capture runs a starts your API and a reverse proxy, then sends and records requests made through the proxy.

ℹ️

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 [command] [options] <openapi-file>

Arguments

openapi-file       an OpenAPI spec file to add an operation to

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
-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

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

update

Updates an OpenAPI spec based on captured requests.

Usage

> optic update [options] <openapi-file> [operations...]

Arguments

openapi-file       an OpenAPI spec
operations         update specific operations in format "get /path/{id}" (default: [])

Options

--har <har-file>                     path to HttpArchive file (v1.2, v1.3)
--postman <postman-collection-file>  path to postman collection
--all                                update all operations

Examples

verify

Verifies an OpenAPI spec based on captured requests

Usage

> optic verify [options] <openapi-file>

Options

--har <har-file>                     path to HttpArchive file (v1.2, v1.3)
--postman <postman-collection-file>  path to postman collection
--exit0                              always exit 0
--upload                             Upload the verification data to optic cloud. Requires the spec to be in optic
                                      (default: false)
--message                            Used in conjunction with `--upload`, sets a message on an uploaded verification.

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")
Diffing API VersionsCapturing Traffic