@useoptic/cli
Advanced tools
How it Works • Install • Document APIs • Detect Changes • Optic GitBot • Contributing License
Optic is like Git, but for your APIs
Similar to
git init
Install Optic with npm or yarn"
yarn add global @useoptic/cli
npm install @useoptic/cli -g
Then run init command:
## Navigate to your API project directory
api init
Setup aliases in for the commands your team runs when building the API in optic.yml
ie npm start -> api start
ie newman run mycollection.json -> postman-tests
name: My API
tasks:
start:
command: npm start
inboundUrl: http://localhost:4000
postman-tests:
command: newman run mycollection.json
usesTask: http://localhost:4000
How does Optic monitor local traffic? Whenever you start your API or run tests using Optic's CLI, it will observe your traffic and surface API diffs. All of this processing is done locally, in the background, by a Rust binary built from the open source code in this repository.
Similar to
git add
Once you add Optic to your API, hit it with some traffic, and document your first endpoints.
You just have to provide Optic with your API paths, and it will document every status code, response body, and request body automatically based on its observations.
You don't have to worry about hitting every possible request/response your first go -- Optic isn't "one-shot", it builds your spec up incrementally as it makes more observations about your API's behavior. If it sees a 200 for an endpoint, and later sees a 400 for the same endpoint, it will help you add the new response -- same for fields, requests, entire endpoints and instances of polymorphism in your API.
api start
[optic] Starting My API API on Port: 3005, with npm run server-start
Similar to
git status
You should keep using the Optic CLI to start your API and run its tests whenever you're developing new functionality. Optic strives to be completely transparent, and the aliases api start and api run <task> are easy to remember.
While Git diffs your, Optic will be sitting there, in the background, diffing your API. You can run api status to check if for diffs:
Similar to staging changes
When Optic detects an API diff, it helps you:
Similar to GitHub's compare page, but for API changes
The Optic GitBot adds an API Changelog during Code Review, so your team understands how the API will change when each PR is merged.
🚦 Prevent Breaking Changes
Discover breaking changes before they're merged. Request compatible changes in code review, or coordinate the breaking changes with consumers.
🔎 API First
Adding explicit API changelogs in PRs facilitates discussion and leads to better API design. It's also a great way to make sure unintended API changes don't get deployed.
✅ Updated Docs
No more doc drift. When you approve an API change Optic also updates the specification.
Install & Set up the GitBot it's free!
📝 Accurate API Documentation - We built Optic to make maintaining accurate specs for your APIs automatic and developer friendly. Once you add Optic to your API repo, it automatically tracks your API’s behavior and maintains a changelog
⚙️ Automated Testing - Automate most of your contract testing. Optic turns your existing tests and development traffic into contract tests, and measures your API coverage from various sources.
👍 Beautiful Docs - Stripe-style documentation for every API managed by Optic.
👋 100% Open Source, Runs locally, data is only stored in your API Repo
Read our about Aidan + Dev's vision for the space Read: Git for APIs
Listen to Optic on Software Engineering Daily
Read API Evangelist on Optic Automatically Generate OpenAPI For Your APIs Just By Using Them
Want to help us design the next features? Book Maintainer Office Hours
MIT
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
FAQs
API CLI from Optic. Document and test your APIs as you build them.
The npm package @useoptic/cli receives a total of 9 weekly downloads. As such, @useoptic/cli popularity was classified as not popular.
We found that @useoptic/cli demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
