The Optic CLI installs the
api command, which is used to manage integration, observation, and documentation of your API. In addition, it provides tools to integrate with other products via OpenAPI exports.
Verifies that Optic can run your tasks and monitor traffic. When initializing Optic with your repository, the guided setup will have you run this command to validate the configuration. If there are any issues, they will be reported on the command line and in the Optic setup UI with recommendations on how to proceed. It takes the name of the task you wish to check, usually
api check start
Provides usage information for
api and subcommands. For subcommands that take parameters, such as
check which take a task name,
--help will provide the same information.
For example, to learn more about the
init command, run:
api init help or
api init --help
Integrates Optic with your API. API init guides you through setup so that you can get running as quickly as possible. There are no required parameters, and the CLI will take you directly to the Optic dashboard to complete and test the integration.
The following optional parameters may be included to pre-populate configuration items:
For example, to set up Optic in proxy mode to document the GitHub API, we might provide the following init command:
api init --inboundUrl https://localhost:4000 --targetUrl https://api.github.com
Runs a task from your
optic.yml file. This is the last step of the initialization process, and the command you will use when you want to observe API traffic in your local environment. It takes the name of the task you wish to run, usually
start. You may have multiple configurations to run tests, or get into advanced configurations, depending on your project.
api run start
Since start is the most common task run, Optic has a command
start that is an alias for
Run has a few flags that can modify the default behavior:
--collect-coveragewill report the coverage of observed traffic over the API specification when the process is stopped.
--exit-on-diffreturns an exit code of
1if unexpected API behavior is returned, such as an undocumented route or a change in behavior on a documented route. Normally, Optic returns
0on successful termination regardless of the behavior observed. This is primarily used in CI/CD scenarios, such as in GitHub Actions, to fail builds when undocumented behavior is detected.
--transparent-proxyconfigures Optic to transparently forward all traffic, which may be necessary for certain application configurations.
Opens your current API specification. This is a quick way to see the current state of the documentation, or jump in and add detail to the endpoints and fields. The Optic dashboard will be opened in your browser on the Documentation page.
An alias for
run start. Start is the default task, which makes it the most commonly run task. This alias saves a few keystrokes:
Lists API diffs observed since your last git commit. This is a quick way on the command line to see if there are any undocumented behaviors that need to be resolved.
--reviewwill open the Optic dashboard to review and document any new endpoints or differences in behavior on existing endpoints. This is a handy way to get into the review process.
--pre-commitreturns an exit code of
1if there are any diffs that need to be resolved in the behavior, such as undocumented endpoints or endpoints whose observed behavior doesn't match the specification. This allows developers to use git hooks such as pre-commit hooks to assure the specification is up to date as part of their normal workflow.
Exports an OpenAPI 3.0.1 specification. This allows you to generate an OpenAPI specification for use in other software, such as third-party documentation generation software. Both
--yaml flags are supported to determine the output format.
scripts command will export an OpenAPI specification and allow you to run a command or script to process that specification. It can even manage dependencies!
generate:oas is great for a one-time run, for workflow integration we recommend
Runs an Optic Script in optic.yml with the current specification. Scripts are defined in the
optic.yml file and allow you to build integration workflows with other tools via OpenAPI exports. Scripts may manage dependencies as well. It takes the name of the Script task to run and has an optional flag to install dependencies if necessary:
api script publish-readme
--installwill install any declared dependencies that are missing, using the provided command. By default, if a dependency is missing the Script task will stop and ask you to use the
--installflag to proceed.
The daemon commands, which include
daemon:stop. These start and stop the Optic daemon, respectively. Under normal circumstances, the daemon is managed by the Optic CLI and you should never have to run either command. To start the daemon, prefer the use of
api spec which will assure you are in the proper project directory.
Removes an endpoint from the specification. This takes the method and
pathId for the appropriate endpoint. The
pathId is most easily determined by browsing the documentation (available with
api spec) and clicking through the target endpoint. The pathId will be part of the URL path for the detailed documentation, of the form
path_ and ten alphanumeric characters). To delete the GET endpoint for pathId
api debug:endpoint-delete GET path_085xFHU7NG