Skip to content

Commit d710ea8

Browse files
devin-ai-integration[bot]jsklandevalog
authored
docs(cli-generator): add hidden quickstart page (#5611)
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: jsklan <100491078+jsklan@users.noreply.github.com> Co-authored-by: Devin Logan <devinannlogan@gmail.com>
1 parent 452f1cc commit d710ea8

2 files changed

Lines changed: 91 additions & 0 deletions

File tree

fern/products/cli-generator/cli-generator.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,7 @@ navigation:
1616
- page: Customization
1717
path: ./customization.mdx
1818
slug: customization
19+
- page: Quickstart
20+
path: ./quickstart.mdx
21+
slug: quickstart
22+
hidden: true
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: Quickstart
3+
description: Generate a working CLI binary from an OpenAPI spec in five steps.
4+
availability: beta
5+
---
6+
7+
<Note title="Early access">
8+
The CLI generator is in early access. [Reach out](https://buildwithfern.com/book-demo?type=cli) to get started.
9+
</Note>
10+
11+
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.
12+
13+
## Prerequisites
14+
15+
- [Fern CLI](https://www.npmjs.com/package/fern-api) v5.37.9 or later (`npm install -g fern-api`)
16+
- [Rust toolchain](https://rustup.rs/) (stable)
17+
- An OpenAPI 3.x spec with at least one endpoint
18+
19+
## Setup
20+
21+
<Steps>
22+
23+
<Step title="Initialize a Fern project">
24+
25+
```bash
26+
mkdir my-api-config && cd my-api-config
27+
fern init --organization my-org
28+
```
29+
30+
This creates a `fern/` directory containing the default configuration files.
31+
</Step>
32+
33+
<Step title="Add your OpenAPI spec">
34+
35+
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).
36+
</Step>
37+
38+
<Step title="Configure the generator">
39+
40+
Replace the contents of `fern/generators.yml`:
41+
42+
```yaml title="fern/generators.yml"
43+
api:
44+
specs:
45+
- openapi: openapi.yml
46+
default-group: cli
47+
groups:
48+
cli:
49+
generators:
50+
- name: fernapi/fern-cli
51+
version: 0.4.0
52+
github:
53+
repo: my-org/my-cli
54+
mode: release
55+
config:
56+
binaryName: my-cli
57+
```
58+
</Step>
59+
60+
<Step title="Generate the CLI">
61+
62+
```bash
63+
fern generate --group cli
64+
```
65+
66+
Fern reads the OpenAPI spec, runs the CLI generator, and writes a complete Rust project to the output path.
67+
</Step>
68+
69+
<Step title="Build and run">
70+
71+
```bash
72+
cd ../my-cli
73+
cargo build
74+
./target/debug/my-cli --help
75+
```
76+
77+
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`.
78+
</Step>
79+
80+
<Step title="Customize the output">
81+
82+
- 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`.
83+
- 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).
84+
- 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).
85+
</Step>
86+
87+
</Steps>

0 commit comments

Comments
 (0)