docs(cli-generator): add hidden self-service pages for fernapi/fern-cli by devin-ai-integration[bot] · Pull Request #5610 · fern-api/docs

devin-ai-integration · 2026-05-22T20:50:54Z

Summary

Adds five hidden documentation pages under the CLI Generator product for early-access users of fernapi/fern-cli. Pages are grouped in a hidden "Self-service guides" section: invisible in the sidebar for normal browsing, but when a user visits any page via direct URL, the full group is visible for navigation between them.

PR #5472 status: Merged and live. This PR does not duplicate any of its content (Features, Authentication, OpenAPI extensions, Customization). Cross-links to those pages are used where appropriate.

New pages (under /learn/cli-generator/guides/):

Quickstart — 5-step end-to-end setup guide with a directory layout diagram and prominent callout for the local-file-system path-resolution gotcha
Configuration reference — all generators.yml config: block options (binaryName), output locations, and multi-spec workspace setup
GraphQL support — quickstart for generating a CLI from a GraphQL introspection schema, command tree structure
Distribution — debug/release builds, TLS backend selection (native-tls vs rustls), cargo-dist setup, publishing channels (GitHub Releases, npm, Homebrew)
Troubleshooting — seven common first-time issues with solutions (wrong output dir, missing auth, OpenSSL errors, old CLI version, committed /target/, etc.)

Open questions from the ticket that could not be resolved without Niels:

namespace: behavior (one binary per namespace, or one binary with subcommands per namespace?) — documented based on source code analysis (subcommands)
Regeneration clobbering behavior — not documented (out of scope for this PR, flagged for follow-up)

Resolves FER-10757

Review & Testing Checklist for Human

Verify all five new pages render correctly in the preview deploy (navigation should NOT show them in the sidebar when browsing other pages)
Visit one hidden page directly and confirm the other four appear in the sidebar for navigation
Check cross-links between new pages and existing pages (Authentication, Features, Customization) resolve correctly
Review the path-resolution callout in the Quickstart for accuracy against actual fern generate behavior
Verify the GraphQL command tree example matches actual generated CLI output

Notes

All content is based on the generator source code at fern-api/fern/generators/cli/ and the CLI SDK at fern-api/cli-sdk. No information was fabricated.
The ticket asks for Niels to be requested as reviewer on the PR.
Pages use availability: beta frontmatter consistent with existing CLI Generator pages.

Link to Devin session: https://app.devin.ai/sessions/f837d4fee3304207a5d5bb390d983b38

Add five hidden pages under learn/cli-generator/ covering the end-to-end 'new user to working CLI' flow: - Quickstart: 5-step setup guide with path-resolution callout - Configuration reference: generators.yml config block documentation - GraphQL support: quickstart for GraphQL introspection schemas - Distribution: building, TLS backends, cargo-dist, publishing - Troubleshooting: common first-time issues and solutions All pages are hidden (reachable by direct URL, absent from nav sidebar). Existing pages from PR #5472 (Features, Authentication, OpenAPI extensions, Customization) are not duplicated — cross-linked where appropriate. FER-10757

devin-ai-integration · 2026-05-22T20:50:56Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment and CI monitoring

github-actions · 2026-05-22T20:51:34Z

+
+When omitted, the generator derives the name from the API's display name (kebab-cased). Multi-spec workspaces must set this field explicitly.
+
+Choose this value carefully: changing it later breaks shell scripts that reference environment variables or the binary path.


📝 [vale] _{reported by reviewdog 🐶}
[FernStyles.Adverbs] Remove 'carefully' if it's not important to the meaning of the statement.

github-actions · 2026-05-22T20:51:34Z

+
+Use `rustls` when:
+- Targeting musl-based Linux (Alpine, scratch Docker images)
+- Cross-compiling for ARM or other architectures


📝 [vale] _{reported by reviewdog 🐶}
[FernStyles.Acronyms] 'ARM' has no definition.

github-actions · 2026-05-22T20:51:34Z

+- Distributing to environments where system OpenSSL is unavailable or outdated
+
+<Note>
+The `rustls` backend does not read the OS certificate store. Users who need custom CA certificates must set the `<NAME>_CA_BUNDLE` environment variable. See [Features](/learn/cli-generator/get-started/features#tls-proxies-and-ca-bundles) for details.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Contractions] Use 'doesn't' instead of 'does not'.

github-actions · 2026-05-22T20:51:34Z

+The `rustls` backend does not read the OS certificate store. Users who need custom CA certificates must set the `<NAME>_CA_BUNDLE` environment variable. See [Features](/learn/cli-generator/get-started/features#tls-proxies-and-ca-bundles) for details.
+</Note>
+
+## cargo-dist


📝 [vale] _{reported by reviewdog 🐶}
[FernStyles.Headings] 'cargo-dist' should use sentence-style capitalization.

github-actions · 2026-05-22T20:51:34Z

+
+## Publishing channels
+
+### GitHub Releases


📝 [vale] _{reported by reviewdog 🐶}
[FernStyles.Headings] 'GitHub Releases' should use sentence-style capitalization.

github-actions · 2026-05-22T20:51:34Z

+fern upgrade
+```
+
+This updates to the latest CLI version. Verify with `fern --version` (v5.37.9 or later required).


⚠️ [vale] _{reported by reviewdog 🐶}
[FernStyles.Current] Avoid time-relative terms like 'latest' that become outdated

github-actions · 2026-05-22T20:51:34Z

+
+This updates to the latest CLI version. Verify with `fern --version` (v5.37.9 or later required).
+
+## `/target/` directory accidentally committed


📝 [vale] _{reported by reviewdog 🐶}
[FernStyles.Adverbs] Remove 'accidentally' if it's not important to the meaning of the statement.

github-actions · 2026-05-22T20:51:34Z

+
+## `/target/` directory accidentally committed
+
+The generator does not ship a `.gitignore` in the output. After the first build, add one:


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Contractions] Use 'doesn't' instead of 'does not'.

github-actions · 2026-05-22T20:51:34Z

+
+## `generators.yml` vs `generators.yaml`
+
+Fern expects `generators.yml` (not `.yaml`). If the CLI cannot find your configuration, check the file extension.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Contractions] Use 'can't' instead of 'cannot'.

github-actions · 2026-05-22T20:51:34Z

+
+1. **Rust toolchain version**: The generated project requires a stable Rust toolchain. Run `rustup update stable`.
+2. **Stale `Cargo.lock`**: If you previously generated with a different generator version, delete `Cargo.lock` and rebuild: `cargo build`.
+3. **Feature flag mismatch**: If you added features to `Cargo.toml` manually, verify they are compatible with the current template version.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Contractions] Use 'they're' instead of 'they are'.

github-actions · 2026-05-22T20:53:31Z

🌿 Preview your docs: https://fern-preview-devin-1779482846-cli-generator-hidden-pages.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

- Use contractions (doesn't, can't, they're) per Microsoft style - Sentence-style heading capitalization - Remove adverbs (carefully, accidentally) - Avoid undefined acronyms (ARM → aarch64) - Avoid time-relative terms (latest)

devin-ai-integration

Devin Review found 3 potential issues.

View 4 additional findings in Devin Review.

devin-ai-integration · 2026-05-22T21:27:57Z

+## Multi-spec workspaces
+
+A single CLI can combine multiple OpenAPI specs into one command tree. Each spec can optionally be placed under a namespace:
+
+```yaml title="fern/generators.yml"
+api:
+  specs:
+    - openapi: core.yml
+    - openapi: billing.yml
+      namespace: billing
+default-group: cli
+groups:
+  cli:
+    generators:
+      - name: fernapi/fern-cli
+        version: 0.5.0
+        output:
+          location: local-file-system
+          path: ../../my-cli
+        config:
+          binaryName: my-cli
+```
+
+Specs without a `namespace` merge flat at the top level of the command tree. Specs with a `namespace` appear under a subcommand:
+
+```bash
+my-cli users list              # from core.yml
+my-cli billing invoices list   # from billing.yml
+```
+
+When a namespace matches a top-level resource in the incoming spec, the CLI hoists that resource's methods to avoid repetition (`billing billing invoices list` becomes `billing invoices list`).
+
+<Note>
+`binaryName` is required for multi-spec workspaces — there is no automatic derivation when multiple specs are present.
+</Note>


🔴 Multi-spec workspaces content duplicated across configuration.mdx and existing customization.mdx

The new configuration.mdx (lines 74–108) restates the multi-spec workspaces concept — introductory sentence, bash examples, and namespace-collision hoisting behavior — that already exists in fern/products/cli-generator/customization.mdx:35-55. Per AGENTS.md rules: "Before creating new content, search the repo for existing pages that already cover the topic. Prefer updating over duplicating" and "One page owns the full explanation; every other page that touches the topic links to it rather than restating it." One page should be canonical for multi-spec workspaces and the other should link to it with a brief sentence.

Was this helpful? React with 👍 or 👎 to provide feedback.

Fixed in 7bc923e — removed the duplicated behavioral description (bash examples, hoisting behavior) from configuration.mdx. The config page now keeps the generators.yml YAML example and links to the Customization page for namespace interaction details and Rust-level behavior.

- Move hidden pages into a 'Self-service guides' hidden section so navigating to one page shows the others in the sidebar - Fix 'See [page]' link phrasing: embed links on natural noun phrases instead of standalone 'See X for details' sentences (AGENTS.md) - Remove multi-spec behavioral duplication between configuration.mdx and customization.mdx: keep config YAML in configuration.mdx, link to customization.mdx for Rust-level namespace behavior - Update cross-links for new /guides/ URL segment

Hidden sections remove the entire group from navigation, so sibling pages aren't visible in the sidebar. Instead, each hidden page now includes a shared CardGroup snippet linking to all five self-service guides, letting users navigate between them from any page. Reverts the hidden-section approach back to individually hidden pages under 'Get started' with a shared Markdown snippet for the nav cards.

Replace custom 'output: location: github' with standard Fern generator github config (github: repository: + mode:) and link to generators.yml reference for mode details.

devin-ai-integration

Devin Review found 1 new potential issue.

View 9 additional findings in Devin Review.

devin-ai-integration · 2026-05-22T21:51:41Z

+  mode: pull-request
+```
+
+Fern pushes the generated CLI source to the specified GitHub repository. When your spec changes, Fern opens a PR against your CLI repo with the updated source. The `mode` field supports `pull-request`, `release`, and `push` — the [generators.yml reference](/learn/sdks/reference/generators-yml-reference#github) covers each mode in detail.


🔴 Incorrect page slug in internal link: generators-yml-reference should be generators-yml

The link /learn/sdks/reference/generators-yml-reference#github uses the file name (generators-yml-reference) instead of the configured page slug. In fern/products/sdks/sdks.yml:276, the page has slug: generators-yml. Per the AGENTS.md link checking rules, URLs must be built from the YAML config slugs, not file paths. The correct URL path segment is generators-yml. Additionally, the #github anchor targets an #### heading (fern/products/sdks/reference/generators-yml-reference.mdx:836), but per AGENTS.md rules, internal anchors only resolve for ## / ### headings, so the anchor won't work either.

Suggested change

Fern pushes the generated CLI source to the specified GitHub repository. When your spec changes, Fern opens a PR against your CLI repo with the updated source. The `mode` field supports `pull-request`, `release`, and `push` — the [generators.yml reference](/learn/sdks/reference/generators-yml-reference#github) covers each mode in detail.

Fern pushes the generated CLI source to the specified GitHub repository. When your spec changes, Fern opens a PR against your CLI repo with the updated source. The `mode` field supports `pull-request`, `release`, and `push` — the [generators.yml reference](/learn/sdks/reference/generators-yml) covers each mode in detail.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration Bot requested a review from devalog as a code owner May 22, 2026 20:50

github-actions Bot reviewed May 22, 2026

View reviewed changes

devin-ai-integration Bot requested a review from Swimburger May 22, 2026 20:51

style: address vale linting feedback

1272383

- Use contractions (doesn't, can't, they're) per Microsoft style - Sentence-style heading capitalization - Remove adverbs (carefully, accidentally) - Avoid undefined acronyms (ARM → aarch64) - Avoid time-relative terms (latest)

jsklan self-requested a review May 22, 2026 21:19

devin-ai-integration Bot commented May 22, 2026

View reviewed changes

This comment was marked as resolved.

Sign in to view

devin-ai-integration Bot added 3 commits May 22, 2026 21:35

fix: reference graphql-schema.json in GraphQL quickstart config

322272d

fix: use standard github output config format in configuration reference

c9d6ad5

Replace custom 'output: location: github' with standard Fern generator github config (github: repository: + mode:) and link to generators.yml reference for mode details.

devin-ai-integration Bot closed this May 22, 2026

devin-ai-integration Bot mentioned this pull request May 22, 2026

docs(cli-generator): add hidden quickstart page #5611

Merged

2 tasks

devin-ai-integration Bot commented May 22, 2026

View reviewed changes


		When omitted, the generator derives the name from the API's display name (kebab-cased). Multi-spec workspaces must set this field explicitly.

		Choose this value carefully: changing it later breaks shell scripts that reference environment variables or the binary path.


		This updates to the latest CLI version. Verify with `fern --version` (v5.37.9 or later required).

		## `/target/` directory accidentally committed


		## `/target/` directory accidentally committed

		The generator does not ship a `.gitignore` in the output. After the first build, add one:


		## `generators.yml` vs `generators.yaml`

		Fern expects `generators.yml` (not `.yaml`). If the CLI cannot find your configuration, check the file extension.

	Fern pushes the generated CLI source to the specified GitHub repository. When your spec changes, Fern opens a PR against your CLI repo with the updated source. The `mode` field supports `pull-request`, `release`, and `push` — the [generators.yml reference](/learn/sdks/reference/generators-yml-reference#github) covers each mode in detail.
	Fern pushes the generated CLI source to the specified GitHub repository. When your spec changes, Fern opens a PR against your CLI repo with the updated source. The `mode` field supports `pull-request`, `release`, and `push` — the [generators.yml reference](/learn/sdks/reference/generators-yml) covers each mode in detail.

Conversation

devin-ai-integration Bot commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Review & Testing Checklist for Human

Notes

Uh oh!

devin-ai-integration Bot commented May 22, 2026

🤖 Devin AI Engineer

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

devin-ai-integration Bot commented May 22, 2026 •

edited

Loading

github-actions Bot commented May 22, 2026 •

edited

Loading

devin-ai-integration Bot May 22, 2026 •

edited

Loading