feat(cli): add tree command

[kanoru3101]

What/Why/How?

Adds a redocly tree command that prints the structure of an API description — its paths, operations, and the component $ref chains between them — for quick orientation in any API (single- or multi-file) and $ref impact analysis in CI and code review.

The default mode renders the document structure (root → paths → operations → component chains), bundling the description first so a multi-file API shows the same full tree as its single-file form;
--uses <component|path|file> shows only the part that depends on the given node, plus an affected-operations summary;
--files switches to the file-level $ref graph;
--format outputs stylish (default), json, mermaid, or dot;
--output/-o writes any format to a file instead of stdout.
Works fully with OpenAPI 2.0/3.x; AsyncAPI and Arazzo render as a flat list of their top-level $ref'd components.

Reference

Related VSCE issue

Testing

Examples with docs

Screenshots (optional)

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

---

Note

Low Risk
New read-only CLI feature built on existing bundle/resolve; no auth or data mutation. Lint config-lint skip is a small behavioral tweak for graph output formats.

Overview
Adds redocly tree, a new CLI command that visualizes API descriptions as dependency graphs for orientation and $ref impact analysis.

Default structure view bundles the spec first, then walks paths → operations → component chains (OpenAPI 2/3); multi-file layouts collapse to the same tree as a single bundled file. --files switches to a cross-file $ref graph and can merge several APIs in one run. --used-by filters to dependents of a component, path, operation, or file, with flexible matchers (JSON pointers, shorthand ids, bare names) and CI-friendly behavior (warnings on unknown inputs, exit 0). Output supports stylish, json, mermaid, dot, plus --output.

Also skips config-lint when lint uses mermaid or dot formats (same as other single-document formats), documents the command, and adds unit and e2e coverage.

^{Reviewed by Cursor Bugbot for commit e111d75. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 64fb2dd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@redocly/cli	Minor
@redocly/openapi-core	Minor
@redocly/respect-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	81.32% (🎯 81%)	7723 / 9497
🔵	Statements	80.68% (🎯 80%)	8042 / 9967
🔵	Functions	84.26% (🎯 84%)	1542 / 1830
🔵	Branches	73.42% (🎯 73%)	5222 / 7112

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/cli/src/types.ts	100%	100%	100%	100%
packages/cli/src/commands/lint.ts	94.33%	87.17%	100%	94.33%	76-78, 143, 177
packages/cli/src/commands/tree/build-graph.ts	100%	94.44%	100%	100%
packages/cli/src/commands/tree/build-structure.ts	96.29%	85.36%	100%	98.68%	132, 148, 157
packages/cli/src/commands/tree/filter-affected.ts	100%	100%	100%	100%
packages/cli/src/commands/tree/index.ts	0%	0%	0%	0%	50-258
packages/cli/src/commands/tree/match-affected-by.ts	100%	100%	100%	100%
packages/cli/src/commands/tree/node-id.ts	97.5%	95.45%	100%	100%	18
packages/cli/src/commands/tree/print/dot.ts	100%	100%	100%	100%
packages/cli/src/commands/tree/print/json.ts	100%	100%	100%	100%
packages/cli/src/commands/tree/print/mermaid.ts	100%	75%	100%	100%
packages/cli/src/commands/tree/print/stylish.ts	100%	100%	100%	100%

Generated in workflow #10554 for commit 64fb2dd by the Vitest Coverage Report Action

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.00x ± 0.01
cli-next	▓ 1.01x ± 0.01	▓ 1.00x ± 0.01	▓ 1.00x (Fastest)

[RomanHotsiy]

This seems to only show details about split spec.

I think we need it not about the file strcuture but about the OpenAPI iteslef.

E.g. if there is one spec in one file I would expect affected to still work listing me the path names.

[kanoru3101]

@cursor review

[kanoru3101]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e111d75. Configure here.}

[adamaltman]

How can you control the depth? Full depth seems not so useful to me.

[kanoru3101]

How can you control the depth? Full depth seems not so useful to me.

Right now there is no depth control — the command always prints the full tree. It is still finite: recursion stops with the 🔁 emoji (for example schemas/MenuSection 🔁). You can narrow the output only with --uses (impact subtree).

I can add --depth <n>,

Most tree tools print the full depth by default and limit it with a flag. So I would keep the full tree as the default. Or do you prefer a limited default?

[adamaltman]

For tree I use these regularly: