User guide
Installing OpticIntegrating OpticContinuous DocumentationAPI Designer & DocsGenerator
Back to home page

Installing Optic

You can install the Optic CLI directly from NPM.

# With npm 
npm install @useoptic/cli -g
# With Yarn
yarn add global @useoptic/cli

This installs the Optic API CLI on your computer. The API CLI runs Optic locally so you can design, document and test the behavior of your API while you develop it locally.

Integrating Optic

How Optic Works

Optic learns your API's specification by watching how it behaves while it is being developed and tested. If the observed behavior deviates from the published API specification, Optic will ask you if you want to  'merge' changes into your spec, or 'mark them as errors'.

This workflow makes it easy to keep your documentation up-to-date and it ensures that developers do not accidentally break the API's contract while they are building other features.

(optional) Importing OpenAPI Spec

If you currently have an OpenAPI specification that describes your API, you can import it to Optic. It's probably not as accurate as you would hope, but Optic can quickly fix the inaccuracies.

# Navigate to your API Repo 
cd /path/to/api/root

# Run Init with import flag (both JSON and YAML are supported)
api init --import /path/to/oas.json 

Setting up Optic to work with your API

Adding Optic to your API is easy.

  • Run api init to configure Optic to work with your API
  • Change the port that the API listens on in development. Optic's proxy will point to the new port and make your API accessible on the original port.
  • Going forward, use our api start command to run your API server locally.

Running API Init

Open your terminal of choice and change your working directory to your API's root directory. Then run api init and provide the following information:

  • API Name:  Provide the name of your API (this can be changed later)
  • Port: Provide Optic with the port you run your API on locally. The proxy will expose your API on this port so you don't have to update your API clients.
  • Command to start API server: The command to start your API. Optic expects this command to hang while your API is running. If that's not the case, contact us on Intercom or on GitHub.

Changing your Port

Optic passes an environment variable into your API process called OPTIC_API_PORT. The port in the environment variable is where Optic will forward traffic from its proxy. You should configure your API to bind to that port while your API is running in development.

Every team has a different way of choosing which port to bind to in development vs. production so it's difficult to prescribe a set of common code changes. Here's pseudocode describing the changes you need to make and a concrete example from one of our Node APIs: 

# Before
PORT = ENV.PRODUCTION_PORT || 3005 (current dev port)
# After
// Before
app.listen(process.ENV.PORT || 3005)
// After
app.listen(process.ENV.PORT || process.ENV.OPTIC_API_PORT)

Having trouble? Contact us on Intercom (chat in the bottom right and we'll help you out

Continuous Documentation (Beta)

Optic documents your API as you develop it meaning your docs are accurate, and never out-of-date. All you have to do is start your API with our api start command and Optic does the rest.

# From your API repo
api start 

Beta Access

Here's our write up on how the Continuous Documentation feature currently works.

The feature is in the final stages of Beta and will be released in the next few weeks. You can use api start to begin collecting data about your API's behavior and evolution, but you won't be able to use that data unless you join the Beta or wait for the general release. If you're interested in being part of the Beta visit this page and fill out the Typeform survey.

API Designer & Docs

Optic ships with our beautiful, open source, visual API Designer and Docs Viewer. These tools run locally and only save data in your git repository.

For Developers

Optic is great for all of your team's API consumers because it provides:

  • Docs that are always up-to-date (with Continuous Documentation)
  • Git Hooks that detect and prevent accidental breaking changes
  • Fully Searchable
  • Provides built-in change logs for the API
For API Designers

Optic is the most powerful API designer available today:

  • A beautiful and intuitive tool for designing your Shapes and API Requests
  • Runs locally and is 100% open source
  • Fully compatible with OpenAPI / Swagger
  • Powerful primitives absent from OpenAPI. Optic has built in support for Maps, References, Identifiers, and Generics.
  • Generics (ie PaginatedListOf[User], PaginatedListOf[Posts]) make it easy to share and reuse API conventions
# To Run the API Designer and Docs run 
api spec 

Or try the API Designer and Doc Viewer with a popular API:


Optic makes it easy to generate server code, client SDKs, static documentation, tests, OpenAPI specs and much more.

What would you be interested in generating?