Developer setup

The Optic CLI lints OpenAPI, tests for breaking changes, and tracks API changes in Optic Cloud.

Install the Optic CLI

npm install -g @useoptic/optic

Get started

Lint an OpenAPI spec

Optic has built in linting support for OpenAPI - run the lint command to check for formatting errors and run lint rules.

optic lint openapi.yml

Diff changes in your OpenAPI spec

Optic computes the effective API changes between two git refs, and runs checks.

optic diff openapi.yml --base main --check

Capture traffic

Optic can capture real traffic by intercepting browser traffic or by forwarding requests to a server.

Using the system proxy

First, set up a https tls certificate Optic can use to read https traffic

optic setup-tls

Then run the following command

optic capture openapi.yml https://api.github.com

And then visit https://api.github.com/users (opens in a new tab). You should notice traffic being captured in your terminal! You can use this with your own website as long as your website is making API requests.

Using the reverse proxy

Alternatively you can run Optic in a reverse proxy mode:

optic capture openapi.yml https://api.github.com --reverse-proxy
> Optic proxy is running at https://localhost:8000 - send traffic to this host. Traffic will be forwarded to https://api.github.com and will be recorded

Then, in a separate terminal, make a curl request to the Optic proxy

curl localhost:8000/users

You should notice traffic being captured in your terminal.

Using captured traffic

Once you have traffic, we can use that traffic to update our OpenAPI spec, or to verify your API documentation.

You can run optic update to update your OpenAPI specification to traffic

optic update openapi.yml --all

Alternatively, you can use the captured traffic to verify your API documentation

optic verify openapi.yml

We also have in-depth guides capturing, updating and verifying:

• Creating a spec from traffic
• Updating an existing spec from traffic
• Verifying your OpenAPI file with traffic

Log in with cloud

Once you've installed the CLI you can log in to Optic - the CLI can be used to interact with Optic Cloud where you can store the entire history of your API and share it with your team.

optic login

You can also set up Optic to run in CI, follow our guide for GitHub or GitLab. Setting Optic up in CI also gets you:

• Beautiful documentation with history
• Automatic breaking change detection and consistent naming conventions standards
• API statistics such as changes over time and breaking changes introduced in the last 6 months