docs(cli-generator): add hidden quickstart page#5611
Conversation
Add a hidden self-service quickstart guide for the CLI generator. Covers end-to-end setup: init, spec, config, generate, build/run. Includes prominent Warning callout for the path-resolution gotcha (local-file-system paths resolve relative to fern/, not repo root). Resolves FER-10757 (partial — quickstart only)
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
|
🌿 Preview your docs: https://fern-preview-devin-1779486477-cli-generator-quickstart.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
Updated version of fern-cli and removed warning about output paths.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| ```yaml title="fern/generators.yml" | ||
| api: | ||
| specs: | ||
| - openapi: openapi.yml | ||
| default-group: cli | ||
| groups: | ||
| cli: | ||
| generators: | ||
| - name: fernapi/fern-cli | ||
| version: 0.4.0 | ||
| github: | ||
| repo: my-org/my-cli | ||
| mode: release | ||
| config: | ||
| binaryName: my-cli | ||
| ``` |
There was a problem hiding this comment.
🟡 Quickstart generators.yml configures only GitHub output but step 5 assumes local output at ../my-cli
The generators.yml example in step 3 configures only github: repo: ... mode: release, which pushes generated code to a GitHub repository (per the generators.yml reference and the CLI generator overview: "Fern opens a PR against your CLI repo with the generated source"). However, step 5 instructs users to cd ../my-cli and cargo build, assuming a local directory exists. Without an output: location: local-file-system section (the pattern used by all SDK quickstarts, e.g., fern/products/sdks/generators/typescript/quickstart.mdx:39-41), no local my-cli directory is created. Users following this guide step-by-step will fail at step 5.
Expected generators.yml for local generation (based on SDK pattern)
groups:
cli:
generators:
- name: fernapi/fern-cli
version: 0.4.0
output:
location: local-file-system
path: ../my-cli
config:
binaryName: my-cliPrompt for agents
The generators.yml example in step 3 only configures github output (github: repo: my-org/my-cli, mode: release), but step 5 assumes the generated Rust project exists locally at ../my-cli. According to the established pattern in other Fern quickstarts (e.g. fern/products/sdks/generators/typescript/quickstart.mdx), local output requires an explicit output section with location: local-file-system and a path. Either: (1) add an output section to the generators.yml example to match step 5's cd ../my-cli expectation, or (2) modify step 5 to explain that the user needs to clone the generated GitHub repo first, or (3) if the CLI generator's fern generate always writes locally regardless of github config, clarify that in the prose. Also verify whether the github field name should be repo or repository — SDK generators use repository per the generators-yml reference.
Was this helpful? React with 👍 or 👎 to provide feedback.
|
|
||
| - Rename commands, hide endpoints, or patch metadata without forking your spec by layering [overrides and overlays](/learn/cli-generator/get-started/customization#overrides-and-overlays) onto `generators.yml`. | ||
| - Ship one binary that drives multiple APIs by listing them under `api.specs` with [multi-spec merging](/learn/cli-generator/get-started/customization#multi-spec-merging). | ||
| - Add subcommands that don't map to an endpoint — login flows, config helpers, local utilities — with [custom commands](/learn/cli-generator/get-started/customization#custom-commands). |
There was a problem hiding this comment.
🟡 Two em dashes in a single bullet point violates AGENTS.md voice rule
Line 84 contains two em dashes in a single short paragraph (bullet point): — login flows, config helpers, local utilities —. The AGENTS.md rule states: "At most one em dash per short paragraph. Before reaching for a second dash, try a colon (for a list or expansion) or parentheses (for an aside). Multiple dashes in close succession read as AI-generated."
| - Add subcommands that don't map to an endpoint — login flows, config helpers, local utilities — with [custom commands](/learn/cli-generator/get-started/customization#custom-commands). | |
| - Add subcommands that don't map to an endpoint (login flows, config helpers, local utilities) with [custom commands](/learn/cli-generator/get-started/customization#custom-commands). |
Was this helpful? React with 👍 or 👎 to provide feedback.
3 participants
Summary
Adds a single hidden quickstart page for the CLI generator, guiding early-access users through end-to-end setup: project init → OpenAPI spec →
generators.ymlconfig →fern generate→cargo build→ run.Includes a prominent
<Warning>callout for the biggest footgun:local-file-systempaths resolve relative tofern/, not the repo root. Directory layout diagram makes the two-level-up path clear.Page is
hidden: true— absent from sidebar and search, reachable only by direct URL.Resolves FER-10757 (partial — quickstart only; other pages deferred)
Review & Testing Checklist for Human
Notes
Link to Devin session: https://app.devin.ai/sessions/f837d4fee3304207a5d5bb390d983b38