fix(cli): whoami honors --api-key, normalize error JSON schema

- whoami/auth status now validates against the API when --api-key is
  explicitly provided, instead of silently showing saved config
- Error JSON output is now always {"error": {"message": "...", ...}}
  instead of sometimes a string, sometimes an object — consistent
  schema for AI agents and programmatic consumers

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: yeldarby

roboflow/cli/_output.py

@@ -85,17 +85,24 @@ def output_error(
     parsed, human_message = _parse_error_message(message)
 
     if getattr(args, "json", False):
-        # If the raw message was JSON containing an "error" key, unwrap it
-        # so we emit {"error": {message details}} not {"error": {"error": ...}}.
+        # Normalise error to always be {"error": {"message": "..."}} so
+        # consumers see a consistent schema regardless of error source.
         if parsed is not None and "error" in parsed:
-            error_value: Any = parsed["error"]
+            inner: Any = parsed["error"]
         elif parsed is not None:
-            error_value = parsed
+            inner = parsed
         else:
-            error_value = message
-        payload: dict[str, Any] = {"error": error_value}
+            inner = None
+
+        if isinstance(inner, dict):
+            error_obj: dict[str, Any] = dict(inner)
+            error_obj.setdefault("message", human_message)
+        else:
+            error_obj = {"message": human_message}
+
         if hint:
-            payload["hint"] = hint
+            error_obj.setdefault("hint", hint)
+        payload: dict[str, Any] = {"error": error_obj}
         print(json.dumps(payload), file=sys.stderr)
     else:
         msg = f"Error: {human_message}"

roboflow/cli/handlers/auth.py

@@ -188,19 +188,18 @@ def _status(args: argparse.Namespace) -> None:
     workspaces = config.get("workspaces", {})
     default_ws_url = config.get("RF_WORKSPACE")
 
-    # Fall back to --api-key flag or ROBOFLOW_API_KEY env var
-    api_key = getattr(args, "api_key", None) or os.getenv("ROBOFLOW_API_KEY")
+    # Explicit --api-key flag takes priority, then env var
+    explicit_api_key = getattr(args, "api_key", None)
+    api_key = explicit_api_key or os.getenv("ROBOFLOW_API_KEY")
 
-    if not workspaces and not default_ws_url and not api_key:
-        output_error(args, "Not logged in.", hint="Run 'roboflow auth login' to authenticate.", exit_code=2)
-        return  # unreachable, but helps mypy
-
-    if api_key and not default_ws_url:
-        # No config file, but we have an API key — fetch workspace from API
+    # When an explicit --api-key is provided, always validate it against the
+    # API rather than showing saved config — the user wants to check *this* key.
+    if explicit_api_key or (api_key and not default_ws_url):
         import requests
 
         from roboflow.config import API_URL
 
+        assert api_key is not None  # guaranteed by the condition above
         resp = requests.post(API_URL + "/?api_key=" + api_key)
         if resp.status_code == 200:
             ws_url = resp.json().get("workspace", "unknown")
@@ -216,6 +215,10 @@ def _status(args: argparse.Namespace) -> None:
             output_error(args, "API key is invalid or expired.", exit_code=2)
         return
 
+    if not workspaces and not default_ws_url and not api_key:
+        output_error(args, "Not logged in.", hint="Run 'roboflow auth login' to authenticate.", exit_code=2)
+        return  # unreachable, but helps mypy
+
     if not default_ws_url:
         output_error(args, "No default workspace configured.", hint="Run 'roboflow auth set-workspace <id>'.")
         return  # unreachable, but helps mypy
@@ -224,7 +227,7 @@ def _status(args: argparse.Namespace) -> None:
     default_ws = workspaces_by_url.get(default_ws_url)
 
     if default_ws:
-        # Use stored API key, or fall back to flag/env
+        # Use stored API key, or fall back to env var
         display_key = api_key or default_ws.get("apiKey", "")
         masked = dict(default_ws)
         masked["apiKey"] = _mask_key(display_key)

tests/cli/test_annotation_handler.py

@@ -99,7 +99,7 @@ def test_stub_json_mode(self):
             sys.stderr = old
 
         result = json.loads(buf.getvalue())
-        self.assertIn("not yet implemented", result["error"])
+        self.assertIn("not yet implemented", result["error"]["message"])
 
 
 if __name__ == "__main__":

tests/cli/test_deployment_handler.py

@@ -101,7 +101,7 @@ def _fake_handler(args: object) -> None:
         err_output = stderr.getvalue().strip()
         parsed = json.loads(err_output)
         self.assertIn("error", parsed)
-        self.assertIn("401", parsed["error"])
+        self.assertIn("401", parsed["error"]["message"])
 
     def test_wrapped_success_prints_output(self) -> None:
         """On success, wrapped func should replay captured stdout."""

tests/cli/test_output.py

@@ -68,8 +68,8 @@ def test_output_error_json_mode(self) -> None:
             sys.stderr = old_stderr
         self.assertEqual(ctx.exception.code, 1)
         result = json.loads(buf.getvalue())
-        self.assertEqual(result["error"], "something broke")
-        self.assertEqual(result["hint"], "try again")
+        self.assertEqual(result["error"]["message"], "something broke")
+        self.assertEqual(result["error"]["hint"], "try again")
 
     def test_output_error_text_mode(self) -> None:
         from roboflow.cli._output import output_error