fix(ceng-630): Fix JSON output across all commands

[BartoszBlizniak]

This pull request significantly improves the Cloudsmith CLI's handling of output when the --output-format json option is used. It ensures that all informational messages, warnings, and prompts are sent to stderr, while error messages from command results are properly formatted as structured JSON on stdout. The changes will also output click exceptions in JSON format to ensure consistent results being returned when things fail.

The most important changes are:

Deprecation warning:

• The --json parameter used as part of the cloudsmith auth command will be removed in a future release of the CLI. Users are asked to switch back to using --output-format json starting from this release.

Output Handling and JSON Support:

• All commands now route informational messages, warnings, and interactive prompts to stderr when --output-format json is active, and output error messages as structured JSON on stdout. This ensures clean and machine-readable JSON output for all commands.
• Introduced and standardized the use of the utils.should_use_stderr(opts) utility function across all commands to determine when to send output to stderr, replacing previous ad-hoc checks.

Command Updates:

• Updated commands such as auth, check, copy, delete, download, entitlements, list_, and login to use the new stderr logic for informational and prompt messages, and to output results/errors as JSON when requested.

Examples:

Shell redirect will hide all output and present only the result in JSON:

> cloudsmith push raw bart-demo-org/618 README.md -F json --republish --no-wait-for-sync 2>/dev/null | jq
{
  "data": {
    "slug": "readmemd-wzmo",
    "slug_perm": "479DjKoMYEHd",
    "status": "OK"
  }
}

Example download command:

> cloudsmith download bart-demo-org/618 common --outfile pom.xml -F json | jq
{
  "data": {
    "filename": "pom.xml",
    "package": {
      "format": "maven",
      "name": "common",
      "slug": "common-03pom-n6gy",
      "version": "0.3"
    },
    "path": "/Users/**redacted**/Downloads/pom.xml",
    "size": 200913,
    "status": "OK"
  }
}

Error example (Note the information message is coming from stderr so the JSON is left intact and parasable)

> cloudsmith auth --token -o bart-demo-org -F json | jq
Beginning authentication for the bart-demo-org org ... 
{
  "detail": "Not Found",
  "help": {
    "context": "Failed to authenticate via SSO!",
    "hint": "This usually means the user/org is wrong or not visible."
  },
  "meta": {
    "code": 404,
    "description": "Not Found"
  }
}

Click error example:

> cloudsmith list packages bart-demo-org/816 -F json --page 1 --page-all | jq
{
  "detail": "Invalid value for '--page-all' / '--show-all': Cannot be used with --page (-p) or --page-size (-l). (--show-all is an alias for --page-all)",
  "meta": {
    "code": 2,
    "description": "Usage Error"
  },
  "help": {
    "context": "Invalid usage",
    "hint": "Check your command arguments/flags."
  }
}

JSON Error Schema:

{
  "detail": "string",
  "fields": {
    "field_name": ["string (error message)", "string (error message)"]
  },
  "help": {
    "context": "string",
    "hint": "string (optional)"
  },
  "meta": {
    "code": 400,
    "description": "string (e.g. Bad Request)"
  }
}

[Copilot]

Pull request overview

This PR significantly improves JSON output handling across the Cloudsmith CLI by ensuring that when --output-format json is used, all informational messages, warnings, and prompts are sent to stderr, while structured JSON results and errors are sent to stdout. This enables clean, machine-readable JSON output that can be easily parsed by shell scripts and automation tools.

Key changes include:

• Introduction of utility functions (should_use_stderr, get_output_format, maybe_print_status_json) to standardize JSON output detection
• Comprehensive update of exception handling to format API errors as structured JSON
• Implementation of Click exception interception to format usage errors as JSON
• Systematic addition of err=use_stderr parameters to all informational messages across commands
• Addition of JSON output support to commands that previously only had text output
• Deprecation of the --json flag in the auth command in favor of --output-format json

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
cloudsmith_cli/cli/utils.py	Added utility functions for JSON output detection and stderr routing
cloudsmith_cli/cli/exceptions.py	Enhanced API exception handler to output structured JSON errors with proper field handling
cloudsmith_cli/cli/command.py	Added Click exception interception to format usage errors as JSON
cloudsmith_cli/cli/webserver.py	Updated 2FA prompt to use stderr when appropriate
cloudsmith_cli/cli/commands/whoami.py	Updated to route informational messages to stderr and use utility functions
cloudsmith_cli/cli/commands/upstream.py	Applied stderr routing for informational messages and confirmation prompts
cloudsmith_cli/cli/commands/tokens.py	Updated token operations to use stderr routing and handle deprecated json flag
cloudsmith_cli/cli/commands/tags.py	Applied stderr routing for all tag operation messages
cloudsmith_cli/cli/commands/status.py	Added JSON output support for package status with stderr routing
cloudsmith_cli/cli/commands/resync.py	Added JSON output support for resync operations with stderr routing
cloudsmith_cli/cli/commands/repos.py	Updated repository operations to use stderr routing utility
cloudsmith_cli/cli/commands/quota/*.py	Applied stderr routing for quota usage commands
cloudsmith_cli/cli/commands/quarantine.py	Added JSON output support for quarantine operations with stderr routing
cloudsmith_cli/cli/commands/push.py	Significant changes to handle progress bars, add JSON output for push results, and route all informational output to stderr
cloudsmith_cli/cli/commands/policy/*.py	Applied stderr routing for policy management commands
cloudsmith_cli/cli/commands/move.py	Added JSON output support for move operations with stderr routing
cloudsmith_cli/cli/commands/metrics/*.py	Updated metrics commands to use stderr routing utility
cloudsmith_cli/cli/commands/login.py	Added JSON output support and stderr routing for login command
cloudsmith_cli/cli/commands/list_.py	Applied stderr routing for list commands
cloudsmith_cli/cli/commands/entitlements.py	Updated entitlement operations to use stderr routing utility
cloudsmith_cli/cli/commands/download.py	Applied stderr routing for download progress messages
cloudsmith_cli/cli/commands/dependencies.py	Applied stderr routing for dependency listing
cloudsmith_cli/cli/commands/delete.py	Added JSON output support for delete operations with stderr routing
cloudsmith_cli/cli/commands/copy.py	Added JSON output support for copy operations with stderr routing
cloudsmith_cli/cli/commands/check.py	Added JSON output support for service and rate limit checks with stderr routing
cloudsmith_cli/cli/commands/auth.py	Updated authentication to handle deprecated json flag and use stderr routing
CHANGELOG.md	Added deprecation notice and fixed section for JSON output improvements

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.