Weave Code
Laravel Openapi Cli Laravel Package
spatie/laravel-openapi-cli
Turn any OpenAPI spec into dedicated Laravel artisan commands with typed options for path params, query params, and request bodies. Add auth, caching, retries, and error handling, or pair with Laravel Zero to build standalone CLI tools.
Create a Laravel command for your OpenAPI spec(s). Works in apps and other packages. Useful for AI agents.
Frequently asked questions about Laravel Openapi Cli
- How do I install spatie/laravel-openapi-cli in a Laravel application?
- Install it with Composer using composer require spatie/laravel-openapi-cli. Then register a spec in a service provider's boot method by calling OpenApiCli::register('https://api.example.com/openapi.yaml', 'bookstore') on the OpenApiCli facade. There are no migrations or schema changes involved, and the fluent builder lets you chain baseUrl(), auth(), cache() and other options in the same call. A first spec is typically wired up in well under a day, including auth.
- Which Laravel and PHP versions does laravel-openapi-cli support?
- The package targets native Laravel 11, 12 and 13 on PHP 8.x, with Laravel 13 support added in version 1.4.1. It is artisan-first and registers commands dynamically from the spec, so no console kernel rewiring is required. Check the composer.json constraints of the exact version you pin before upgrading your framework.
- Can I use this package with Laravel Zero to build a standalone CLI tool?
- Yes, that is one of the intended use cases. The README explicitly recommends pairing the package with Laravel Zero to ship standalone CLI tools for any API that publishes an OpenAPI spec. In that setup the spec becomes the source of truth for your command surface, so you get new commands as soon as endpoints are added.
- How do I stop generated commands from colliding on the same name?
- Enable useOperationIds() on the registration chain and treat it as mandatory rather than optional. Derived command names can normalize different endpoints to the same slug, for example /books/{id}/reviews and /books/{book_id}/reviews both landing on bookstore:get-books-reviews. Operation IDs give you a stable, unique identifier per endpoint. Do not rely on silent de-duplication at registration time.
- Does the command exit with a non-zero code when the API returns an error?
- This is the first thing to verify in your own environment, because it determines whether the tool is usable in shell pipelines and by AI agents. Test a 4xx and a 5xx response and inspect the exit code, including when onError or retryOn intercepts the response. If failures exit 0, you will need to wrap the command or parse output before trusting it in automation.
- How does auth() work and is the token cached between command invocations?
- auth() takes a closure that is invoked per request, so it is your responsibility to cache tokens inside the service the closure calls. Put the caching in your existing token manager so you do not pay a secrets-store or OAuth round trip on every command run. Version 1.4.0 added an AuthenticationException that aborts with a friendly message and optional hint before the request is sent, instead of surfacing a raw 401.
- How does spec caching work and what happens when the remote spec changes?
- cache(ttl: 600) caches the fetched spec for ten minutes, so a change to a remote document silently changes your CLI surface on the next expiry. That is a real drift risk for anything automated. Vendor or pin the spec locally where the command surface must be predictable, and review spec diffs like you would review code.
- How do I handle rate limits and retries with onError and retryOn?
- retryOn() receives the response and command and returns whether to retry, with maxRetries controlling the ceiling, which makes 401 token refresh and transient 5xx handling straightforward. onError() lets you return a custom warning, such as reading a Retry-After header on a 429, or return false to fall through to default handling. Both accept closures, so you can log, alert or transform responses without forking the package.
- What happens if the OpenAPI spec is malformed or unreachable when the console boots?
- Because commands are registered dynamically from the spec, a broken or unreachable document fails at console kernel boot rather than failing a single command, which is a console-wide failure mode. Registration happens through the facade in a service provider, so you control when it loads and can guard it by environment. Cross-file or external $ref resolution is not clearly documented, so validate any spec that references external documents before relying on it.
- Is spatie/laravel-openapi-cli production ready, and should I pin the version?
- The architecture is sound and easy to remove, but adoption signal is thin at around 42 stars and zero dependents, so you would be among the first non-Spatie production users. The changelog shows a package still finding its edges, including a breaking body-handling change in 1.5.0 that shipped as a minor release. Pin exact versions, never let Composer float the package in CI, and read every changelog entry before upgrading.
Weaver
How can I help you explore Laravel packages today?