|
| 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