An LLM-friendly CLI for exploring OpenAPI documents one layer at a time. Instead of stuffing an entire spec into a prompt, give the model exactly the slice it needs — one resource group, one endpoint, one schema.
Works great for humans too. Outputs plain text or JSON. Also available as phyll (shorter alias, same binary).
Install
Homebrew (macOS, Linux)
cargo install
Download a binary
Grab the latest release for your platform from GitHub Releases.
Linux / macOS:
# Pick your platform:
# x86_64-unknown-linux-gnu (Linux x86_64)
# aarch64-unknown-linux-gnu (Linux ARM64)
# x86_64-apple-darwin (macOS Intel)
# aarch64-apple-darwin (macOS Apple Silicon)
PLATFORM="x86_64-unknown-linux-gnu"
|
Windows:
Download the phyllotaxis-x86_64-pc-windows-msvc.zip from the releases page, extract it, and add the folder to your PATH.
Build from source
Requires Rust (install via rustup).
# Binaries are in target/release/phyllotaxis and target/release/phyll
Verify
Why?
OpenAPI documents get big fast. Dumping one into a prompt creates problems beyond token cost:
- Precision — models hallucinate when they have to pick relevant fields out of thousands. Focused context means fewer mistakes.
- Agent-friendly — an LLM agent can call phyll iteratively: overview → resource → endpoint → schema. Each step is a tool call with a focused response.
- Deterministic — same query, same output. No prompt engineering to extract the right slice.
- Small models work — Haiku, local models, and cost-constrained setups can't fit a full spec. Phyll makes them viable.
Works great for humans too — same progressive disclosure, just without the token math.
Commands
| Command | What it shows |
|---|---|
phyll |
API overview: title, description, base URLs, auth, top resources |
phyll --resources |
All resource groups with endpoint counts |
phyll --resources <name> |
Endpoints in a resource group |
phyll --endpoint <METHOD> <path> |
Full endpoint detail: params, request body, responses |
phyll --schemas |
All schemas |
phyll --schemas <name> |
Schema detail: fields, types, composition |
phyll --schemas <name> --used-by |
Which endpoints use this schema |
phyll --schemas <name> --example |
Generate an example JSON object |
phyll --auth |
Auth schemes and how they're used |
phyll search <term> |
Search across everything |
phyll --callbacks |
Webhook callbacks |
phyll --callbacks <name> |
Callback detail |
phyll init |
Auto-detect OpenAPI documents and write config |
phyll completions <shell> |
Shell completions (bash, zsh, fish, powershell, elvish) |
Global Flags
--doc <name|path> Override which document to use
--json Output JSON instead of text
--expand Inline nested schemas recursively (max depth 5)
--related-limit <n> Cap how many related schemas to show
Endpoint Detail Flags
--context Show related schemas expanded after the endpoint
--example Show an auto-generated example request/response body
How the Layers Work
Phyllotaxis auto-detects OpenAPI documents in your project, or you can run phyll init to configure one. For one-off exploration, pass the file directly with --doc. See Document Discovery for the full resolution order.
The first example uses --doc to show one-off usage. The rest assume a document is already configured.
Level 0: Overview
)
)
)
)
Level 1: Resource Listing
Level 2: Resource Detail
Level 3: Endpoint Detail
)
)
)
{ }
Schema Detail
)
)
)
)
)
Callbacks
Example Generation
Generate example JSON from any schema:
)
{
}
Placeholders are based on the field type and format:
| Type/Format | Placeholder |
|---|---|
string |
"string" |
string/uuid |
"550e8400-e29b-41d4-a716-446655440000" |
string/date-time |
"2024-01-15T10:30:00Z" |
string/email |
"user@example.com" |
string/uri |
"https://example.com" |
integer |
0 |
boolean |
true |
| enum | First enum value |
If the document has example values on schemas or properties, those get used instead. For discriminated unions (oneOf with a discriminator), the type field gets set to the correct mapped value.
Reverse Schema Lookup
Find out which endpoints use a given schema:
)
This catches direct $ref references, allOf/oneOf/anyOf compositions, and schemas nested as fields inside other schemas that an endpoint uses.
Related Schemas (--context)
When you're looking at an endpoint, --context expands the schemas referenced in the request/response body:
)
)
)
)
)
)
For oneOf/anyOf endpoints, --context shows the variant schemas too.
Schema Expansion
)
)
)
)
)
)
Search
Search across resources, endpoints, schemas, security schemes, and callbacks:
Searches resource names/descriptions, endpoint paths/summaries/descriptions, parameter names/descriptions, request body descriptions, response descriptions, schema names/descriptions/field names, and security scheme names/descriptions.
If a match comes from somewhere non-obvious (like a parameter name or description text), the result tells you why it matched.
JSON Output
Every command supports --json. It's pretty-printed in a terminal and compact when piped:
|
Fuzzy Matching
Mistype a name and phyllotaxis suggests close matches:
Document Discovery
Phyllotaxis finds your OpenAPI document in four ways (checked in this order):
--docflag - named document from config or a file path, always winsPHYLLOTAXIS_DOCUMENTenv var - set to a file path; errors if the file doesn't exist, ignored if empty.phyllotaxis.yamlconfig - created byphyll init, checked in the current directory and parents- Auto-detect - scans for
*.yaml/*.yml/*.jsonfiles withopenapi:in the first 200 bytes
Run phyll init to set up a config:
)
For non-interactive setup (CI, scripts), pass the path directly:
Multi-Document Projects
If your project has multiple API documents, use named documents in .phyllotaxis.yaml:
documents:
public: ./api/public.yaml
internal: ./api/internal.yaml
default: public
variables:
tenant: my-org
env: staging
Then pick one by name:
The variables map fills in server URL template variables (e.g., {tenant} becomes my-org in base URL output).
Compatibility
- OpenAPI 3.0.x - fully supported
- OpenAPI 3.1 - not supported (the
openapiv3parser targets 3.0) - Swagger / OpenAPI 2.0 - not supported
- YAML and JSON documents - both work
$refresolution - local and external file references (multi-file documents)
Project Structure
phyllotaxis/
├── src/
│ ├── main.rs # CLI entry point (clap)
│ ├── lib.rs # Public crate API (re-exports)
│ ├── spec.rs # Config loading, document resolution, parsing
│ ├── commands/
│ │ ├── overview.rs # L0: API overview
│ │ ├── resources.rs # L1-L3: resource groups, detail, endpoints
│ │ ├── schemas.rs # Schema listing, detail, expansion, --used-by
│ │ ├── examples.rs # Example generation from schemas
│ │ ├── auth.rs # Security scheme extraction
│ │ ├── search.rs # Cross-type search
│ │ ├── callbacks.rs # Webhook callback extraction
│ │ └── init.rs # Framework detection, interactive setup
│ ├── models/
│ │ ├── resource.rs # Data structs + helpers
│ │ └── schema.rs # SchemaModel, Composition enum
│ └── render/
│ ├── text.rs # Plain text output
│ └── json.rs # JSON output
└── tests/
├── fixtures/
│ ├── petstore.yaml # Test fixture
│ ├── kitchen-sink.yaml # Edge case fixture
│ └── multi-file/ # External $ref test fixture
├── fixture_sanity.rs # Fixture parse validation
├── integration_tests.rs # End-to-end CLI tests
└── lib_tests.rs # Library API tests
Roadmap
| Feature | Status |
|---|---|
External $ref resolution (multi-file documents) |
Done |
Document management UX (persistent --doc, nicknames) |
Planned |
| Remote URL loading (fetch specs from HTTP/HTTPS) | Planned |
| OpenAPI 3.1 support | Planned |
| Swagger / OpenAPI 2.0 support | Planned |
| MCP server (LLM tool integration) | Planned |
See issues for what's being worked on now.
Development
License
Apache-2.0