feat: add user-friendly error messages

src/pieces/app.py

@@ -5,6 +5,7 @@
 
 from pieces.config.constants import PIECES_DATA_DIR
 from pieces.config.migration import run_migration
+from pieces.errors import format_error
 from pieces.headless.exceptions import HeadlessError
 from pieces.headless.models.base import ErrorCode
 from pieces.headless.output import HeadlessOutput
@@ -171,7 +172,11 @@ def main():
         else:
             Settings.logger.critical(e, ignore_sentry=True)
             try:
-                Settings.show_error("UNKNOWN EXCEPTION", e)
+                # Display user-friendly error message
+                friendly_message = format_error(e, include_technical=False)
+                Settings.logger.console_error.print(f"[red]{friendly_message}[/red]")
+                if not Settings.run_in_loop:
+                    sys.exit(2)
             except SystemExit:
                 sentry_sdk.flush(2)
                 raise

src/pieces/errors/__init__.py

@@ -0,0 +1,20 @@
+"""
+User-friendly error handling for Pieces CLI.
+
+This module provides utilities for transforming technical error messages
+into helpful, actionable messages for users.
+"""
+
+from .user_friendly import (
+    UserFriendlyError,
+    ErrorCategory,
+    format_error,
+    get_user_friendly_message,
+)
+
+__all__ = [
+    "UserFriendlyError",
+    "ErrorCategory",
+    "format_error",
+    "get_user_friendly_message",
+]