[tigh-latte]

Description

Each time the CLI renamed a setting, it kept the old name as a silent alias. Users never got a prompt to switch, so the aliases kept piling up and we had no plan to remove them. This PR deprecates the old names in ENG-15245 for removal in 2.0.0. When a user uses one, the CLI prints a single shared warning to stderr.

Before:

$ cloudsmith whoami --org acme -S
Retrieving your authentication status from the API ... OK
You are authenticated as:
User: Jane Doe (slug: jane-doe, email: jane@example.com)

After:

$ cloudsmith whoami --org acme -S
Warning: `-S` is deprecated and will be removed in version 2.0.0. Use `--without-ssl-verify` instead.
Warning: `--org` is deprecated and will be removed in version 2.0.0. Use `--workspace` instead.
Retrieving your authentication status from the API ... OK
You are authenticated as:
User: Jane Doe (slug: jane-doe, email: jane@example.com)

Decision for each alias: deprecate all of them (they keep working until 2.0.0):

Setting	Deprecated name	Replacement
Proxy	--api-proxy	--proxy
	CLOUDSMITH_API_PROXY	CLOUDSMITH_PROXY
	api_proxy config key	proxy
	--allowed-api-proxy-suffixes, CLOUDSMITH_ALLOWED_API_PROXY_SUFFIXES (hidden)	--allowed-proxy-suffixes, CLOUDSMITH_ALLOWED_PROXY_SUFFIXES
SSL verification	--without-api-ssl-verify, -S	--without-ssl-verify
	CLOUDSMITH_WITHOUT_API_SSL_VERIFY	CLOUDSMITH_SSL_VERIFY=0
	api_ssl_verify config key	ssl_verify
Workspace	--org, --organization, --oidc-org, --owner	--workspace
	-o	-w
	CLOUDSMITH_ORG	CLOUDSMITH_WORKSPACE
	org, organization, oidc_org config keys	workspace
Pagination	--show-all	--page-all
cloudsmith auth	--token, --force	--request-api-key
	--json	--output-format json

What changed:

• New cloudsmith_cli/cli/deprecation.py holds the shared warning (Warning: … is deprecated and will be removed in version 2.0.0. Use … instead.). It prints yellow text to stderr, once per run, and prints nothing during shell completion.
• Each deprecated flag spelling is now its own hidden option, so the warning can name the spelling that was used. The old spellings no longer appear in --help.
• Deprecated environment variables warn only when the CLI actually uses them, so they don't warn when the new variable is also set.
• Deprecated config keys warn only when they take effect. They don't warn when the new key in the same section overrides them, when the value is empty, or for api_ssl_verify = true, which is the schema default and impossible to tell apart from an absent key. They also don't warn from the probe reads (relative-config guard, telemetry opt-out).
• auth --token/--force/--json and login/token now use the shared warning. DEPRECATION WARNING: is gone, so every deprecation message uses Warning:. The login text keeps its November 20, 2026 cut-off.
• Credential helper runtimes (credential-helper docker/cargo/pnpm/terraform/generic) print no warning. Package managers run them non-interactively, and older credential-helper install terraform versions wrote --org into ~/.terraformrc. install, uninstall and list still warn.
• The release and binaries workflows now set CLOUDSMITH_WORKSPACE instead of CLOUDSMITH_ORG.
• The README, the default config.ini comments and the credential-helper help text use the new names. The CHANGELOG has a new Deprecated section that records the removal plan.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe)

Additional Notes

One small behaviour change: when someone passes an old and a new flag on the same command line (--org a --workspace b), the new one now wins. Before, the last one won, because they were the same Click option. This matches how the env vars and config keys already resolve. The CHANGELOG notes it. I didn't mark this breaking.

--api-proxy is now a separate parameter, so _guard_untrusted_endpoints takes a proxy_trusted argument. Without it, a proxy given with --api-proxy would be checked like a value from an untrusted directory-relative config.

Open questions from the ticket, resolved:

• Prefix: Warning: (matches login and other CLI warnings).
• Deprecation period: until the next major release (2.0.0), no fixed date.

Not in this PR: removing the aliases (that's for 2.0.0). CLOUDSMITH_API_PROXY doesn't warn on commands that never set up an HTTP session (for example cloudsmith docs), because only the session setup reads it.

Tests: new cloudsmith_cli/cli/tests/test_deprecation.py (45 tests: every flag, env var and config alias; precedence; once-per-run; credential helper suppression; help output; JSON output keeps stdout clean), plus new auth flag cases in test_auth.py.

[Copilot]

🟡 Changes recommended

Alias handling silently drops --show-all during list repos forwarding and can select the wrong Workspace when multiple deprecated flags are supplied.

5 open issues

• Preserve canonical repo parameters during pagination forwarding · New
• Warn on deprecated config in inherited mcp start settings · New
• Honor command-line order among deprecated Workspace aliases · New
• Suppress stale alias warnings after profile overrides · New
• Warn about legacy SSL variable only when selected · New

What changed in this PR

Adds shared deprecation warnings to help CLI users migrate renamed settings before legacy aliases are removed in version 2.0.0.

Changes:

• Introduces hidden legacy options and shared stderr warnings, with credential-helper runtime suppression.
• Adds tests for alias behavior, precedence, warnings, and output handling.
• Updates documentation and workflows to use current setting names.

File	Description
README.md	Documents deprecated settings and current replacements.
cloudsmith_cli/​data/​config.ini	Updates comments with alias removal plans.
cloudsmith_cli/​cli/​validators.py	Supports resolved pagination aliases during validation.
cloudsmith_cli/​cli/​tests/​test_org_option.py	Updates the Workspace alias test description.
cloudsmith_cli/​cli/​tests/​test_deprecation.py	Adds alias and warning regression coverage.
cloudsmith_cli/​cli/​tests/​commands/​test_auth.py	Tests shared warnings for deprecated auth flags.
cloudsmith_cli/​cli/​deprecation.py	Adds shared warning and alias-resolution helpers.
cloudsmith_cli/​cli/​decorators.py	Integrates alias resolution and deprecation warnings.
cloudsmith_cli/​cli/​config.py	Tracks deprecated configuration keys.
cloudsmith_cli/​cli/​commands/​login.py	Uses shared warnings while preserving the login cutoff.
cloudsmith_cli/​cli/​commands/​credential_helper/​pnpm.py	Updates help text about deprecated aliases.
cloudsmith_cli/​cli/​commands/​credential_helper/​docker.py	Updates help text about deprecated aliases.
cloudsmith_cli/​cli/​commands/​credential_helper/​cargo.py	Updates help text about deprecated aliases.
cloudsmith_cli/​cli/​commands/​auth.py	Uses shared warnings for legacy auth flags.
CHANGELOG.md	Records deprecations and precedence changes.
.github/​workflows/​release.yml	Switches to CLOUDSMITH_WORKSPACE.
.github/​workflows/​dev-release.yml	Switches to CLOUDSMITH_WORKSPACE.
.github/​workflows/​binaries.yml	Switches to CLOUDSMITH_WORKSPACE.

_{Review effort: Balanced}