Skip to content

Add Current and Legacy versions to CLI Generator docs - #7810

Open
nerminamiller-postman wants to merge 14 commits into
mainfrom
devin/1794337644-cli-generator-versions
Open

nerminamiller-postman wants to merge 14 commits into
mainfrom
devin/1794337644-cli-generator-versions

Conversation

@nerminamiller-postman

@nerminamiller-postman nerminamiller-postman commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds a Current/Legacy version switcher to the CLI Generator product, set up the same way as the SDKs switcher (#7403).

  • fern/docs.yml: the CLI Generator product gets versions:. Current is products/cli-generator/current.yml (the old nav moved here) and Legacy is products/cli-generator/legacy/legacy.yml. cli-generator.yml now contains navigation: []. Current URLs stay at /learn/cli-generator/get-started/* and Legacy is served at /learn/cli-generator/legacy/get-started/*, so no redirects are needed. Both versions share one changelog.
  • Legacy: a copy of today's generators.yml pages. Each page starts with legacy/snippets/legacy-notice.mdx, which links to the same page in Current and to the SDK Config migration guide. The hidden roadmap page isn't copied.
  • Current: the pages are rewritten for a language: cli target in sdk-config.yml, based on the CLI generator SDK Config summary, feat(cli): send the sdk-config cli target to sdk-gen-api as SDK Config fern#18823, feat(cli): always send the sdk-config cli target to sdk-gen-api fern#18850 and Adi's review of what sdk-gen-core supports:
    • Quickstart: add the target, then run fern generate --target cli.
    • Configuration: CLI settings move under targets[].generation. Adds crateName and oauthTokenEndpoints. packageIdentity becomes the target's package block. distribution becomes output.distribution, with fields renamed to appIdSecretName, privateKeySecretName and tokenSecretName.
    • Authentication: examples now use api.auth.schemes with oauth2 flows. The any strategy is shown with api.auth.requirements.
    • Publishing: uses output.delivery: github and output.publish (registry: npm, trustedPublishing or token).
    • Self-hosted generation: new "Unsupported settings" section. Since feat(cli): always send the sdk-config cli target to sdk-gen-api fern#18850, fern generate always sends the cli target to sdk-gen-api; only --local still translates it to a generators.yml for fern-cli-generator. On that path the device-code flow, redirectUri/redirectUriBackupPorts, successRedirectUrl/errorRedirectUrl, extra request parameters, oauthTokenEndpoints and URL specs fail, and crateName is ignored with a warning.
    • Customization, Custom commands, Features and Overview get smaller updates.
  • Not in Current, because the new generator doesn't support them (they stay in Legacy):
    • Configuration: displayName, banner, extraDependencies, skills, paginationParameters, and the provision flag, parameters and profileParameters. The schema accepts skills, paginationParameters, and (since @postman/sdk-config@0.21.0) banner and the provision fields, but the generator doesn't read them.
    • Authentication: the guided API-key setup (only profiles create --provision exists), the All strategy, and API keys in a query or cookie, OpenID Connect and custom schemes.
    • OpenAPI extensions: x-fern-cli-table and --columns.
  • Old changelog and roadmap links to anchors that no longer exist in Current (#config-options, #displayname, #packageidentity, #guided-api-key-setup) now point to the matching Legacy anchors.

Every complete sdk-config.yml example in Current validates against @postman/sdk-config 0.20.0 and 0.21.0. fern check --warnings reports 0 errors.

Before merge

  • Publishing: Adi deleted his comment asking to hold this page (whether the release, npm publish and Homebrew/Scoop workflows are generated when sdk-gen-api requests a zip). Confirm with him that it's resolved.
  • Open question for Adi: should Current document generation.wireTests.enabled (renamed from generateWireTests)?
  • feat(cli): always send the sdk-config cli target to sdk-gen-api fern#18850 shipped in Fern CLI 5.207.0, which Quickstart and Self-hosted generation now list as the minimum version.
  • sdk-gen-api still picks the generator per organization with the LaunchDarkly flag sdk-gen-rust-cli-enabled; organizations with it off get the old Go CLI generator. Confirm with Adi that it's on for everyone before this ships.

Link to Devin session: https://app.devin.ai/sessions/9ff659dd53594809a591ca88570c81a0
Open in Devin Desktop: https://app.devin.ai/desktop/session/9ff659dd53594809a591ca88570c81a0?variant=devin
Requested by: @nerminamiller-postman


🟢 Devin fixed all 3 findings · Follow Devin's work

Devin Review

… in Current, generators.yml in Legacy

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring


## Named profiles

For APIs where every call carries a tenant identifier (an account SID, an org slug, a workspace), a profile stores it once instead of it being typed on every command. A profile is a named bundle of request context resolved once per invocation: a credential, parameter defaults, [server URL variables](/learn/cli-generator/legacy/get-started/features#server-url-variables), an optional base URL, a [retry limit](/learn/cli-generator/legacy/get-started/features#retries-with-backoff), [transport settings](/learn/cli-generator/legacy/get-started/features#tls-proxies-and-ca-bundles) (request timeout, proxy, CA bundle, TLS verification, and User-Agent suffix), and a default output format. Nothing else is accepted; an unknown key is rejected at write time rather than stored and ignored.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

📝 [vale] <FernStyles.Acronyms> reported by reviewdog 🐶
'SID' has no definition.

</ParamField>

<ParamField path="banner.animate" type="boolean" default="false" required={false}>
When `true`, root `--help` in an interactive terminal plays a short shimmer across the banner, then prints it statically. Pipes, captured output, `NO_COLOR`, `TERM=dumb`, and terminals too small for the banner skip the animation.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

📝 [vale] <FernStyles.Acronyms> reported by reviewdog 🐶
'TERM' has no definition.


`input.properties` is keyed by the spec's parameter names, and each property's `flag` gives the exact flag to pass. Properties without a `flag` are passed through `--params` or `--json`. Operations that support [`--page-all`](#pagination), return binary bodies, or stream also report `paginable`, `binaryResponse`, or `streaming`. The root schema lists the CLI's built-in command groups (`auth`, `completion`, `man`, and `profiles` when [enabled](/learn/cli-generator/legacy/get-started/authentication#named-profiles)) under `builtinCommands`, separate from the spec-derived operations.

## Server URL variables

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

📝 [vale] <FernStyles.Headings> reported by reviewdog 🐶
'Server URL variables' should use sentence-style capitalization.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

🌿 Preview your docs: https://fern-preview-devin-1794337644-cli-generator-versions.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

@Postman-AdiBarHalevi Postman-AdiBarHalevi left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Hi Nermina, I checked the new pages against what the generator actually does (sdk-gen-core and the 0.20.0 schema). I did not run a generation. A few things in these docs say we support something that we don't.

The docs say we support it, but we don't

  • Guided API-key setup (the section on the Authentication page, and the provisionOperation text in Configuration). Only profiles create --provision exists.
  • skills and paginationParameters. The schema accepts them, but the generator ignores them.
  • x-fern-cli-table and --columns on the OpenAPI extensions page. The generator doesn't support them.

FriendlyName: "{cli} for {user} on {host}"
profileParameters:
AccountSid: username
An operation that mints a profile's remote credential (an API key), and how its response maps onto that credential. When set, `profiles create` can call the operation with the credentials already in the caller's environment and store the mapped response fields in the OS keychain without printing the secret. In an interactive terminal, it also turns on the [guided API-key flow](/learn/cli-generator/get-started/authentication#guided-api-key-setup) for `auth login` and `profiles create`. Paired with `revokeOperation`, a profile owns its API key end to end: minted when the profile is created, revoked by `profiles remove --revoke`. When omitted, the guided flow is off.

@Postman-AdiBarHalevi Postman-AdiBarHalevi Nov 12, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The guided API-key flow mentioned here doesn't exist in the generated CLI. Only profiles create --provision does: it calls the operation and stores the credential. I'd remove this sentence, and the "Guided API-key setup" section on the Authentication page.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Removed in 13014bb: both guided-flow sentences are gone from provisionOperation, and the "Guided API-key setup" section is gone from Current Authentication. The two old links to that anchor (the 2026-10-19 changelog entry and the hidden roadmap page) now point to the Legacy page.


<ParamField path="profiles.provisionOperation.flag" type="string" default="provision" required={false}>
Long name of the `profiles create` flag that mints a key, without the leading dashes. Must start with a lowercase letter and contain only `[a-z0-9-]`. Set `api-key` to expose `--api-key`; `--provision` stays accepted as a hidden alias, so existing scripts keep working.
<ParamField path="skills" type="boolean" toc={true}>

@Postman-AdiBarHalevi Postman-AdiBarHalevi Nov 12, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

skills passes validation, but the generator never reads it, so it does nothing today. I'd leave it out for now, or say it isn't available yet.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Removed skills from Current Configuration in 13014bb, and from the --local ignored-settings list.

- `{host}`: the machine's short hostname

A parameter the profile already sets takes precedence over the configured value. Values can't contain quotes, backslashes, or control characters.
<ParamField path="paginationParameters" type="string[]" toc={true}>

@Postman-AdiBarHalevi Postman-AdiBarHalevi Nov 12, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Same as skills: the schema accepts paginationParameters, but nothing in the generator reads it, so it has no effect.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Removed paginationParameters from Current Configuration in 13014bb, and from the --local ignored-settings list.

…rrent

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…es from Current

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor

@Postman-AdiBarHalevi thanks for checking. Here's what changed:

  • 13014bb: removed the guided API-key setup, skills and paginationParameters.
  • 889d40d: removed x-fern-cli-table/--columns (the Table output section of OpenAPI extensions, plus the link to it from Features). Also, from your first version of the summary:
    • Authentication no longer says every scheme type is supported. API keys in a header are listed as supported, and a sentence says query or cookie API keys, OpenID Connect and custom schemes are skipped.
    • Removed the All strategy row.
    • Removed the package.extraDependencies bullet from Custom commands.
  • Publishing: holding, see the inline thread.

One question: your first version said generateWireTests is now generation.wireTests.enabled: true and the generator honors it, but the edited summary leaves that out. Should Current Configuration document wireTests.enabled? It passes validation against the 0.20.0 schema. I'll add it once you confirm.

@devin-ai-integration

Copy link
Copy Markdown
Contributor

@Postman-AdiBarHalevi re your Publishing comment (I can't reply in that thread because it's a file-level comment): I'll leave publishing.mdx as it is until you report back on the delivery: github run through the API. I've added this to the PR description's "Before merge" list.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

@devin-ai-integration devin-ai-integration Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Devin Review found 3 findings. Devin automatically fixed all 3 findings.

Fixed by Devin (3)
  • Regeneration overwrites unprotected custom hooks — customCommands now says the module is left alone only once protected by .fernignore or generation.ignoreFiles, linking to the Generated files section.
  • Hook example targets missing commands — Hooks section now states the example assumes a pets command group with a get command.
  • Legacy changelog links miss their features — Dry-run, prefixed API-key headers, prompts, object shorthand, macOS signing and multi-spec changelog entries now link to the matching Legacy sections.

View findings in Devin Review · Follow Devin's work

Devin Review

…ved features to Legacy

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor

Updated the Current pages to match sdk-gen-core develop (Adi's Static CLI epic, SDK-3082) and added an SDK Config tip like the SDK docs have (products/cli-generator/snippets/sdk-config-tip.mdx, on Overview, Quickstart and Configuration).

Added back to Current (now in the generator): x-fern-cli-table, --query, --properties, --help --format json, --params/--json, --user-agent-suffix, <NAME>_TIMEOUT_SECS, auth login/logout/status with the OS keyring, OpenID Connect sent as a bearer token, hooks and the new custom commands layout (cli/src/commands/custom/), the errors/completion/man commands, and the release.yml + publish-npm.yml pipeline.

Removed from Current, still on Legacy (not in the generator yet; most are in Adi's backlog): PKCE/device-code login, OAuth token cache, named profiles, provision/revoke, proxy/CA bundle/_INSECURE, <NAME>_LOG/--debug, retries, --dry-run, --schema, server URL variables, x-fern-global-parameters, x-fern-groups, tag-based group help, userAgentSuffixFlag, splitTypeCrates, oauthTokenEndpoints, macOS code signing. Changelog and API-definition links to those anchors now go to Legacy.

Self-hosted generation now says --local builds with the Legacy generator image.

Check before merge: npm trusted publishing now lists release.yml as the workflow filename, because publish-npm.yml is a reusable workflow that release.yml calls. Confirm with Adi that npm accepts the calling workflow's name.

Previews:

Written by Devin

github-actions[bot]

This comment was marked as resolved.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants