Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fern-support merged 3 commits into from
May 23, 2026
+91 −0
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9cdb55d
docs(cli-generator): add hidden quickstart page
devin-ai-integration[bot] May 22, 2026
3cfddbd
Change fern-cli version and clean up documentation
jsklan May 22, 2026
b415d0b
add steps component, restructure a bit
devalog May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions fern/products/cli-generator/cli-generator.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,7 @@ navigation:
- page: Customization
path: ./customization.mdx
slug: customization
- page: Quickstart
path: ./quickstart.mdx
slug: quickstart
hidden: true
87 changes: 87 additions & 0 deletions fern/products/cli-generator/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
title: Quickstart
description: Generate a working CLI binary from an OpenAPI spec in five steps.
availability: beta
---

<Note title="Early access">
The CLI generator is in early access. [Reach out](https://buildwithfern.com/book-demo?type=cli) to get started.
</Note>

This guide walks through generating a CLI from an OpenAPI spec and running it locally. By the end you will have a compiled binary that [maps every API endpoint to a subcommand](/learn/cli-generator/get-started/openapi-extensions#command-structure), with [authentication](/learn/cli-generator/get-started/authentication), [output formatting](/learn/cli-generator/get-started/features#output-formatting), and [pagination](/learn/cli-generator/get-started/features#pagination) wired up from your spec.

## Prerequisites

- [Fern CLI](https://www.npmjs.com/package/fern-api) v5.37.9 or later (`npm install -g fern-api`)
- [Rust toolchain](https://rustup.rs/) (stable)
- An OpenAPI 3.x spec with at least one endpoint

## Setup

<Steps>

<Step title="Initialize a Fern project">

```bash
mkdir my-api-config && cd my-api-config
fern init --organization my-org
```

This creates a `fern/` directory containing the default configuration files.
</Step>

<Step title="Add your OpenAPI spec">

Place your spec at `fern/openapi.yml` (or any path you reference in the next step). The spec must include at least one path, and any `securitySchemes` declared under `components` become the credentials the CLI [reads at runtime](/learn/cli-generator/get-started/authentication).
</Step>

<Step title="Configure the generator">

Replace the contents of `fern/generators.yml`:

```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
```
Comment on lines +42 to +57
Copy link
Copy Markdown
Contributor Author

@devin-ai-integration devin-ai-integration Bot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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-cli
Prompt 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.
Open in Devin Review

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

</Step>

<Step title="Generate the CLI">

```bash
fern generate --group cli
```

Fern reads the OpenAPI spec, runs the CLI generator, and writes a complete Rust project to the output path.
</Step>

<Step title="Build and run">

```bash
cd ../my-cli
cargo build
./target/debug/my-cli --help
```

The `--help` output shows the full command tree: top-level commands derived from OpenAPI tags, subcommands from individual operations, and built-in utilities like `completion` and `man`.
</Step>

<Step title="Customize the output">

- 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).
Copy link
Copy Markdown
Contributor Author

@devin-ai-integration devin-ai-integration Bot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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."

Suggested change
- 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).
Open in Devin Review

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

</Step>

</Steps>
Loading