fix(no-ticket): stop 401 hint from asserting a permissions problem

[BartoszBlizniak]

Description

Fixes the misleading credentialed 401 hint from issue #77, plus an exit-code bug found while verifying it.

The hint. A 401 tells the CLI that authentication failed; it does not tell it why. The old hint asserted one specific cause — "you don't have the permission to perform this action" — which is 403 semantics, contradicts the 401 - Unauthorized status printed directly above it, and sends users chasing the wrong kind of bug (exactly what the issue reporter describes). get_401_error_hint now names the possible causes without picking one: This usually means your API key is invalid, expired, or lacks access to this resource - check your credentials and try again. The SSO-token, token-command, and no-credential branches are unchanged.

The exit codes. Writing the renderer tests surfaced that CliRunner reports exit_code == 0 for a 401. That turned out to be half artefact, half real bug. AliasGroup.main (cloudsmith_cli/cli/command.py:138) runs click with standalone_mode=False so it can render click's own errors as JSON, so click returns the code passed to ctx.exit() instead of raising SystemExit. Every entrypoint therefore has to wrap main() in sys.exit(). Three of the four did; python -m cloudsmith_cli called it bare and always exited 0, so a failed push or an unauthorised request looked like success to CI and to scripts.

Entrypoint	Before	After
cloudsmith console script (pip / uv / pipx)	sys.exit(main()) in the installer-generated script	unchanged
Standalone binaries (PyInstaller)	sys.exit(main()) in packaging/pyinstaller/entry.py	unchanged
Homebrew	bin.write_exec_scriptexecs the bundled binary and inherits its status	unchanged
python -m cloudsmith_cli	bare main() — always exited 0	sys.exit(main())

This is the same bug #328 fixed for the PyInstaller entry point; __main__.py was the one caller it missed. AGENTS.md:21 documents python -m cloudsmith_cli ... as a supported invocation.

Type of Change

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

Additional Notes

Tests: test_exceptions.py asserts the complete hint text and renders it through the registered command tree in both text and JSON output, with --config-file and --credentials-file pointed at pytest's tmp_path so a real config on the machine cannot influence the result. test_entrypoint_exit_codes.py covers the exit-code contract for all three entrypoints — main() returns the status, python -m raises SystemExit(401), and the non-importable PyInstaller entry still wraps main() in sys.exit(). Reverting __main__.py to a bare main() fails the python -m test. The binaries stay covered by packaging/smoketest.sh:114, which already requires whoami against an unreachable API to exit non-zero.

Verified end to end against a local server returning HTTP 401: both python -m cloudsmith_cli whoami and the cloudsmith console script exit 145, which is 401 & 0xFF after POSIX truncation. Passing the raw status to sys.exit() is pre-existing behaviour and stays non-zero for every status the CLI can raise (403→147, 404→148, 422→166, 429→173, 500→244); no real HTTP status is a multiple of 256.

Full suite: 633 passed, 40 skipped. pre-commit hooks pass, including ruff format, ruff check, typos, and the credential/private-key detectors.

[Copilot]

Pull request overview

• This PR improves the Cloudsmith CLI’s user-facing handling of HTTP 401 responses by removing a misleading “permissions” assertion from the credentialed hint, and fixes python -m cloudsmith_cli to correctly propagate non-zero exit codes (matching the other shipped entrypoints).

Changes:

• Update the 401 “credential present” hint to describe likely causes (invalid/expired/insufficient access) without asserting a 403-style permissions error.
• Wrap cloudsmith_cli.__main__ with sys.exit(main()) so python -m cloudsmith_cli reports failures via exit status.
• Add tests covering both the rendered hint (text + JSON) and the exit-code contract across entrypoints.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
cloudsmith_cli/cli/tests/test_exceptions.py	Adds assertions for the updated 401 hint and verifies it survives both text and JSON renderers via real command invocation.
cloudsmith_cli/cli/tests/test_entrypoint_exit_codes.py	Adds regression tests ensuring main()’s returned status is propagated by python -m and that the PyInstaller entrypoint wraps main() in sys.exit().
cloudsmith_cli/cli/exceptions.py	Updates the credentialed 401 hint text to avoid implying a specific authorization failure.
cloudsmith_cli/main.py	Fixes module entrypoint to sys.exit(main()) so failures are non-zero when invoked with python -m.
CHANGELOG.md	Documents both fixes under Unreleased.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (3)

cloudsmith_cli/cli/tests/test_entrypoint_exit_codes.py:46

• The new helper name and docstring use British “unauthorised”; the project guideline requires Americanized spelling. Rename this to unauthorized_api and update its call sites in this test.

def unauthorised_api():
"""Patch the whoami API call to raise a 401."""

cloudsmith_cli/cli/tests/test_entrypoint_exit_codes.py:31

• The new helper name and docstring use British “unauthorised”; the project guideline requires Americanized spelling. Rename this to unauthorized_args and update its call sites in this test.

This issue also appears on line 45 of the same file.

def unauthorised_args(config_dir):
"""Return args for a whoami that will raise a 401, isolated from real config."""

CHANGELOG.md:12

• Use the project’s required Americanized spelling: “unauthorized.”

- `python -m cloudsmith_cli` now exits non-zero when a command fails. `AliasGroup.main` runs click with `standalone_mode=False` so click returns the exit code from `ctx.exit()` rather than raising `SystemExit`, and the module entrypoint discarded that return value — so a failed push, or an unauthorised request, exited 0. The `cloudsmith` console script and the standalone binaries already wrapped `main()` in `sys.exit()` and were unaffected.