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