Repository navigation
Add Current and Legacy versions to CLI Generator docs - #7810
nerminamiller-postman wants to merge 14 commits into
Conversation
… in Current, generators.yml in Legacy Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
|
I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".
|
|
|
||
| ## 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. |
There was a problem hiding this comment.
📝 [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. |
There was a problem hiding this comment.
📝 [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 |
There was a problem hiding this comment.
📝 [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>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
There was a problem hiding this comment.
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
provisionOperationtext in Configuration). Onlyprofiles create --provisionexists. skillsandpaginationParameters. The schema accepts them, but the generator ignores them.x-fern-cli-tableand--columnson 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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}> |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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}> |
There was a problem hiding this comment.
Same as skills: the schema accepts paginationParameters, but nothing in the generator reads it, so it has no effect.
There was a problem hiding this comment.
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>
|
@Postman-AdiBarHalevi thanks for checking. Here's what changed:
One question: your first version said |
|
@Postman-AdiBarHalevi re your Publishing comment (I can't reply in that thread because it's a file-level comment): I'll leave |
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>
There was a problem hiding this comment.
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.
…ved features to Legacy Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
|
Updated the Current pages to match sdk-gen-core Added back to Current (now in the generator): 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/ Self-hosted generation now says Check before merge: npm trusted publishing now lists Previews: |
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>
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 getsversions:. Current isproducts/cli-generator/current.yml(the old nav moved here) and Legacy isproducts/cli-generator/legacy/legacy.yml.cli-generator.ymlnow containsnavigation: []. 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.generators.ymlpages. Each page starts withlegacy/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.language: clitarget insdk-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:fern generate --target cli.targets[].generation. AddscrateNameandoauthTokenEndpoints.packageIdentitybecomes the target'spackageblock.distributionbecomesoutput.distribution, with fields renamed toappIdSecretName,privateKeySecretNameandtokenSecretName.api.auth.schemeswithoauth2flows. Theanystrategy is shown withapi.auth.requirements.output.delivery: githubandoutput.publish(registry: npm,trustedPublishingortoken).fern generatealways sends theclitarget to sdk-gen-api; only--localstill translates it to agenerators.ymlforfern-cli-generator. On that path thedevice-codeflow,redirectUri/redirectUriBackupPorts,successRedirectUrl/errorRedirectUrl, extra request parameters,oauthTokenEndpointsand URL specs fail, andcrateNameis ignored with a warning.displayName,banner,extraDependencies,skills,paginationParameters, and the provisionflag,parametersandprofileParameters. The schema acceptsskills,paginationParameters, and (since@postman/sdk-config@0.21.0)bannerand the provision fields, but the generator doesn't read them.profiles create --provisionexists), theAllstrategy, and API keys in a query or cookie, OpenID Connect and custom schemes.x-fern-cli-tableand--columns.#config-options,#displayname,#packageidentity,#guided-api-key-setup) now point to the matching Legacy anchors.Every complete
sdk-config.ymlexample in Current validates against@postman/sdk-config0.20.0 and 0.21.0.fern check --warningsreports 0 errors.Before merge
generation.wireTests.enabled(renamed fromgenerateWireTests)?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