From 1012253460a2ea9ffd572ba155cee15f5f9ed4a6 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sat, 1 Aug 2026 17:07:36 +0000 Subject: [PATCH 1/2] docs: document fern generate --package, --package-mode, and --package-only Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../cli-api-reference/pages/commands.mdx | 31 ++++++++++++++++++- fern/products/sdks/deep-dives/self-hosted.mdx | 2 ++ 2 files changed, 32 insertions(+), 1 deletion(-) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index fca845fbb..2ef311fb6 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -181,7 +181,7 @@ hideOnThisPage: true ```bash - fern generate [--group ] [--api ] [--version ] [--preview] [--fernignore ] [--local] [--force] [--no-replay] + fern generate [--group ] [--api ] [--version ] [--preview] [--fernignore ] [--local] [--force] [--no-replay] [--package] [--package-mode ] [--package-only] ``` @@ -294,6 +294,35 @@ hideOnThisPage: true `--no-replay` works only for local generation (`--local`). + ### package + + Use `--package` to build a distributable artifact for each generator that outputs to the local file system. The artifact is written to a `fern-dist/` folder inside the output directory, so an SDK can be shared internally without publishing to a registry. Artifacts are language-specific: an npm tarball, a Python wheel and sdist, a JAR, a NuGet package, a gem, a Composer zip, a crate, or, for Go, a `-source.zip` containing the module source to reference with a `replace` directive in `go.mod`. + + ```bash + fern generate --group node-sdk-local --version 0.0.1 --package + ``` + + ### package-mode + + Use `--package-mode ` to choose where packaging runs. The default, `local`, uses the language toolchains installed on your machine. `docker` runs each toolchain inside the generator's official Docker image, so no toolchain is required on the host. + + ```bash + fern generate --group node-sdk-local --version 0.0.1 --package --package-mode docker + ``` + + ### package-only + + Use `--package-only` to keep only the artifact: after packaging, everything in the output directory except `fern-dist/` is deleted, so the generated SDK source isn't left behind. `--package-only` implies `--package`. Deletion happens per generator, so a generator whose packaging failed keeps its source for debugging. + + ```bash + fern generate --group node-sdk-local --version 0.0.1 --package-only --package-mode docker + # SDKs/twilio-core-ts-sdk/ contains only fern-dist/twilio-core-0.0.1.tgz + ``` + + + The earlier `--pack` and `--pack-mode` flags were renamed to `--package` and `--package-mode` and no longer exist. Update any scripts that use them. + + diff --git a/fern/products/sdks/deep-dives/self-hosted.mdx b/fern/products/sdks/deep-dives/self-hosted.mdx index 609423a85..83460cbf0 100644 --- a/fern/products/sdks/deep-dives/self-hosted.mdx +++ b/fern/products/sdks/deep-dives/self-hosted.mdx @@ -146,6 +146,8 @@ fern generate --group python-sdk --local To pull generator images from a private registry your organization controls instead of Docker Hub, see [Private registry setup](#private-registry-setup). +To share a locally generated SDK internally without publishing it to a registry, add [`--package`](/learn/cli-api/cli-reference/commands#package), which builds a distributable artifact into a `fern-dist/` folder inside the output directory. + From 44b9c9f56ba204a8fad2ff715de3e1db18128f3f Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Mon, 3 Aug 2026 12:06:48 +0000 Subject: [PATCH 2/2] docs: fold --pack content into --package flags and fix package-mode values Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../cli-api-reference/pages/commands.mdx | 45 +++++++++++++++---- fern/products/sdks/deep-dives/self-hosted.mdx | 2 +- .../reference/generators-yml-reference.mdx | 2 + 3 files changed, 40 insertions(+), 9 deletions(-) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index 2ef311fb6..b343d3ca6 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -181,7 +181,7 @@ hideOnThisPage: true ```bash - fern generate [--group ] [--api ] [--version ] [--preview] [--fernignore ] [--local] [--force] [--no-replay] [--package] [--package-mode ] [--package-only] + fern generate [--group ] [--api ] [--version ] [--preview] [--fernignore ] [--local] [--force] [--no-replay] [--package] [--package-mode ] [--package-only] ``` @@ -296,27 +296,56 @@ hideOnThisPage: true ### package - Use `--package` to build a distributable artifact for each generator that outputs to the local file system. The artifact is written to a `fern-dist/` folder inside the output directory, so an SDK can be shared internally without publishing to a registry. Artifacts are language-specific: an npm tarball, a Python wheel and sdist, a JAR, a NuGet package, a gem, a Composer zip, a crate, or, for Go, a `-source.zip` containing the module source to reference with a `replace` directive in `go.mod`. + Use `--package` to build a distributable package artifact for every generator in the run whose [output location](/learn/sdks/reference/generators-yml#output) is `local-file-system`. Artifacts are written to a `fern-dist/` folder inside that generator's output directory, so a generated SDK can be handed to internal consumers without publishing it to a public registry. `--package` works with both cloud and local (`--local`) generation, and implies full project output so the artifact includes the project metadata files (`pyproject.toml`, `README.md`, and similar) it needs to build. ```bash - fern generate --group node-sdk-local --version 0.0.1 --package + # Package every local-file-system output + fern generate --package + + # Package one group generated locally + fern generate --group plantstore-python-sdk --local --package ``` + | Language | Artifact | + |----------|----------| + | TypeScript | npm tarball (`.tgz`) | + | Python | wheel (`.whl`) | + | Java | JAR | + | C# | NuGet package (`.nupkg`) | + | Ruby | gem (`.gem`) | + | PHP | Composer archive (`.zip`) | + | Rust | crate (`.crate`) | + | Go | module source zip (`-source.zip`) | + + Go modules have no binary package format, so the Go artifact is a zip of the generated module source, excluding `fern-dist/` and `.git/`. Fern builds it in-process: it produces the same artifact in either package mode and requires no Go toolchain. Consumers unzip it and point their `go.mod` at the unzipped directory: + + ```go title="go.mod" + require github.com/plantstore/plantstore-go v0.0.0 + + replace github.com/plantstore/plantstore-go => ../plantstore-go + ``` + + Swift SDKs are distributed as Swift Package Manager source packages, so packaging logs a warning instead of producing an artifact: share the output directory or reference it as a local package dependency. If packaging fails for one or more generators, the CLI reports them together as `Packaging failed for: ` and removes any empty `fern-dist/` directory it created. + + `--package` can't be combined with `--preview` or with docs generation (`--docs`). + ### package-mode - Use `--package-mode ` to choose where packaging runs. The default, `local`, uses the language toolchains installed on your machine. `docker` runs each toolchain inside the generator's official Docker image, so no toolchain is required on the host. + Use `--package-mode ` to choose where `--package` runs the packaging toolchains. `host` (the default) uses the toolchains installed on the machine (`npm`, `pip`, `gradle`, `dotnet`, `gem`, `composer`, `cargo`). `docker` runs each toolchain inside its official image (`node`, `python`, `gradle`, `dotnet/sdk`, `ruby`, `composer`, `rust`) with the output directory mounted, so no language toolchains are required locally. Docker mode uses `docker` as the container runtime unless you pass `--runner podman`. ```bash - fern generate --group node-sdk-local --version 0.0.1 --package --package-mode docker + fern generate --group plantstore-python-sdk --package --package-mode docker ``` + `--package-mode` requires `--package` or `--package-only`. + ### package-only - Use `--package-only` to keep only the artifact: after packaging, everything in the output directory except `fern-dist/` is deleted, so the generated SDK source isn't left behind. `--package-only` implies `--package`. Deletion happens per generator, so a generator whose packaging failed keeps its source for debugging. + Use `--package-only` to keep only the artifact: after packaging, everything in the output directory except `fern-dist/` is deleted, so the generated SDK source isn't left behind. `--package-only` implies `--package`. Deletion happens per generator, so a generator whose packaging failed keeps its source for debugging, as does a generator that produces no artifact at all (Swift). `.git`, `.fernignore`, and any top-level path a `.fernignore` entry covers are always preserved. ```bash - fern generate --group node-sdk-local --version 0.0.1 --package-only --package-mode docker - # SDKs/twilio-core-ts-sdk/ contains only fern-dist/twilio-core-0.0.1.tgz + fern generate --group plantstore-node-sdk --version 0.0.1 --package-only --package-mode docker + # SDKs/plantstore-node-sdk/ contains only fern-dist/plantstore-0.0.1.tgz ``` diff --git a/fern/products/sdks/deep-dives/self-hosted.mdx b/fern/products/sdks/deep-dives/self-hosted.mdx index 83460cbf0..7551793da 100644 --- a/fern/products/sdks/deep-dives/self-hosted.mdx +++ b/fern/products/sdks/deep-dives/self-hosted.mdx @@ -146,7 +146,7 @@ fern generate --group python-sdk --local To pull generator images from a private registry your organization controls instead of Docker Hub, see [Private registry setup](#private-registry-setup). -To share a locally generated SDK internally without publishing it to a registry, add [`--package`](/learn/cli-api/cli-reference/commands#package), which builds a distributable artifact into a `fern-dist/` folder inside the output directory. +To share a locally generated SDK internally without publishing it to a registry, add [`--package`](/learn/cli-api-reference/cli-reference/commands#package), which builds a distributable artifact into a `fern-dist/` folder inside the output directory. diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 1fa9ebdb2..59d6e96e5 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -939,6 +939,8 @@ Set to "local-file-system" for local output Local directory path where generated files will be saved + +To turn a local output into an installable artifact (npm tarball, wheel, JAR, and so on) without publishing it to a registry, run [`fern generate --package`](/learn/cli-api-reference/cli-reference/commands#package).