Component
Feature Description
Remove the --api-version command line parameter from the CLI and instead automatically align the API version with the autogenerated OpenAPI client bundled in the project.
Problem Statement
The current approach allows users to manually specify an API version via --api-version, which introduces the risk of version mismatches between the CLI and the underlying OpenAPI client. This can lead to subtle bugs, failed requests, or undefined behavior when the CLI attempts to communicate with a server using an incompatible or unsupported API version.
Additionally, exposing API version selection at the CLI level adds unnecessary cognitive overhead for users, who typically expect the CLI to "just work" with the correct versioning baked in.
Proposed Solution
- Remove the
--api-version flag from all CLI commands.
- Ensure the CLI always uses the API version defined by the autogenerated OpenAPI client.
- Tie API versioning strictly to the client generation process, so that updating the client automatically updates the effective API version used by the CLI.
- Optionally expose the resolved API version via a read-only command (e.g.,
synk version or synk api-version) for debugging and transparency.
This ensures that the CLI and API client remain tightly coupled and eliminates the possibility of user-induced version drift.
Alternatives Considered
- Keeping
--api-version but validating it against the client at runtime: This still introduces complexity and does not eliminate the risk of mismatch or confusion.
- Allowing overrides only via environment variables: Reduces CLI surface but still permits divergence and hidden state.
- Supporting multiple API versions simultaneously: Adds significant maintenance overhead and complexity without a clear use case at this stage.
Additional Context
The CLI is already generated or tightly coupled with an OpenAPI client, which implicitly defines the supported API surface and version. Treating the client as the single source of truth for API compatibility simplifies both the mental model and the implementation.
This change aligns with the general principle of reducing configuration surface and avoiding user-controlled switches for internal compatibility concerns.
Component
Feature Description
Remove the
--api-versioncommand line parameter from the CLI and instead automatically align the API version with the autogenerated OpenAPI client bundled in the project.Problem Statement
The current approach allows users to manually specify an API version via
--api-version, which introduces the risk of version mismatches between the CLI and the underlying OpenAPI client. This can lead to subtle bugs, failed requests, or undefined behavior when the CLI attempts to communicate with a server using an incompatible or unsupported API version.Additionally, exposing API version selection at the CLI level adds unnecessary cognitive overhead for users, who typically expect the CLI to "just work" with the correct versioning baked in.
Proposed Solution
--api-versionflag from all CLI commands.synk versionorsynk api-version) for debugging and transparency.This ensures that the CLI and API client remain tightly coupled and eliminates the possibility of user-induced version drift.
Alternatives Considered
--api-versionbut validating it against the client at runtime: This still introduces complexity and does not eliminate the risk of mismatch or confusion.Additional Context
The CLI is already generated or tightly coupled with an OpenAPI client, which implicitly defines the supported API surface and version. Treating the client as the single source of truth for API compatibility simplifies both the mental model and the implementation.
This change aligns with the general principle of reducing configuration surface and avoiding user-controlled switches for internal compatibility concerns.