Skip to main content

api run

Runs a task from your optic.yml file. This is the command you will use to start a task, such as for observing traffic or running tests. It takes the name of the task you wish to run, usually start. You may have multiple, advanced task configurations depending on your project.

api start

Since start is the most common task run, Optic has a command start that is an alias for run start.

Flags & Options#

Run has a few flags that can modify the default behavior:

  • -c/--print-coverage prints how much of the documented API is covered by traffic seen in the capture session. The coverage prints once the session is terminated (ctrl+c or when tests finish running).
  • --ci Enables CI-specific behavior. This enables --print-coverage, --exit-on-diff, and pass-exit-code.
  • --exit-on-diff returns an exit code of 1 if unexpected API behavior is returned, such as an undocumented route or a change in behavior on a documented route. Normally, Optic returns 0 on 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.
  • --pass-exit-code returns the exit code of your task. If you are using a dependent task, the exit code of the dependent command (not the base command) will be passed through. This flag is overridden by - - - --verbose which provides extra troubleshooting information at task startup, task end, and when traffic is observed. We recommend using this when configuring a new task.

Examples#

To run your start task:

api run start
> api run baseline-ignores --collect-diffs[optic] Running dependent task start...[optic] Review the API Diff at http://localhost:34444/apis/2/diffs[optic] Optic is observing requests made to http://localhost:3001...[optic] Observed Unexpected API Behavior. Run "api status"

Special notes#

The run tasks start a proxy, and will set the host headers to the targetUrl if provided. If not (such as when only a command and inboundUrl are given) the inboundUrl, which should be localhost, will be used in the request host header.

Issues & Contributing#

Having trouble? Open an issue on GitHub

Have an idea for changing this command? Here's where it lives in the repo. PRs welcome!

Need help or want to talk with us about a use case? Join Contributing on Discord