feat(cmd): add JSON output mode for programmatic parsing

- Add global --json flag for structured output
- Create CommandOutput struct with success/error/claims/token fields
- Update all encode commands to output JSON when --json flag is used
- Update all decode commands to output JSON when --json flag is used
- Maintain backward compatibility with human-readable output as default
- Add SilenceErrors and SilenceUsage to prevent duplicate error messages
- Ensure consistent exit codes (0 for success, 1 for error)

Resolves #58

Author: sgaunet

cmd/decode-es.go

@@ -1,6 +1,8 @@
 package cmd
 
 import (
+	"encoding/json"
+	"errors"
 	"fmt"
 
 	"github.com/sgaunet/jwt-cli/pkg/cryptojwt"
@@ -71,11 +73,19 @@ Tip: The token is the three-part string (header.payload.signature) produced by t
 				j = privKeyDecoderWithValidation(privateKeyFile, validationOpts)
 			}
 
-			t, err := j.Decode(token)
+			claims, err := j.Decode(token)
 			if err != nil {
-				return fmt.Errorf("decoding failed: %w", err)
+				errMsg := fmt.Sprintf("decoding failed: %v", err)
+				output(CommandOutput{Success: false, Error: errMsg})
+				return errors.New(errMsg)
 			}
-			fmt.Println(t)
+			// Parse claims string as JSON for structured output
+			var claimsData any
+			if err := json.Unmarshal([]byte(claims), &claimsData); err != nil {
+				// If claims aren't valid JSON, treat as raw string
+				claimsData = claims
+			}
+			output(CommandOutput{Success: true, Claims: claimsData})
 			return nil
 		},
 	}

cmd/decode-hs.go

@@ -1,6 +1,8 @@
 package cmd
 
 import (
+	"encoding/json"
+	"errors"
 	"fmt"
 
 	"github.com/sgaunet/jwt-cli/pkg/cryptojwt"
@@ -58,11 +60,19 @@ Tip: The token is the three-part string (header.payload.signature) produced by t
 			}
 
 			j := decoderWithValidation([]byte(secret), allowWeakSecret, validationOpts)
-			t, err := j.Decode(token)
+			claims, err := j.Decode(token)
 			if err != nil {
-				return fmt.Errorf("decoding failed: %w", err)
+				errMsg := fmt.Sprintf("decoding failed: %v", err)
+				output(CommandOutput{Success: false, Error: errMsg})
+				return errors.New(errMsg)
 			}
-			fmt.Println(t)
+			// Parse claims string as JSON for structured output
+			var claimsData any
+			if err := json.Unmarshal([]byte(claims), &claimsData); err != nil {
+				// If claims aren't valid JSON, treat as raw string
+				claimsData = claims
+			}
+			output(CommandOutput{Success: true, Claims: claimsData})
 			return nil
 		},
 	}

cmd/decode-rs.go

@@ -1,6 +1,8 @@
 package cmd
 
 import (
+	"encoding/json"
+	"errors"
 	"fmt"
 
 	"github.com/sgaunet/jwt-cli/pkg/cryptojwt"
@@ -70,11 +72,19 @@ Tip: The token is the three-part string (header.payload.signature) produced by t
 				j = privKeyDecoderWithValidation(privateKeyFile, validationOpts)
 			}
 
-			t, err := j.Decode(token)
+			claims, err := j.Decode(token)
 			if err != nil {
-				return fmt.Errorf("decoding failed: %w", err)
+				errMsg := fmt.Sprintf("decoding failed: %v", err)
+				output(CommandOutput{Success: false, Error: errMsg})
+				return errors.New(errMsg)
 			}
-			fmt.Println(t)
+			// Parse claims string as JSON for structured output
+			var claimsData any
+			if err := json.Unmarshal([]byte(claims), &claimsData); err != nil {
+				// If claims aren't valid JSON, treat as raw string
+				claimsData = claims
+			}
+			output(CommandOutput{Success: true, Claims: claimsData})
 			return nil
 		},
 	}

cmd/encode-es.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 
 	"github.com/sgaunet/jwt-cli/pkg/cryptojwt"
@@ -54,9 +55,11 @@ Tip: Payload must be valid JSON. Common claims include 'sub' (subject), 'exp' (e
 			j := encoder(privateKeyFile)
 			t, err := j.Encode(payload)
 			if err != nil {
-				return fmt.Errorf("encoding failed: %w", err)
+				errMsg := fmt.Sprintf("encoding failed: %v", err)
+				output(CommandOutput{Success: false, Error: errMsg})
+				return errors.New(errMsg)
 			}
-			fmt.Println(t)
+			output(CommandOutput{Success: true, Token: t})
 			return nil
 		},
 	}

cmd/encode-hs.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 
 	"github.com/sgaunet/jwt-cli/pkg/cryptojwt"
@@ -52,9 +53,11 @@ Tip: Payload must be valid JSON. Common claims include 'sub' (subject), 'exp' (e
 			j := encoderWithOpts([]byte(secret), allowWeakSecret)
 			t, err := j.Encode(payload)
 			if err != nil {
-				return fmt.Errorf("encoding failed: %w", err)
+				errMsg := fmt.Sprintf("encoding failed: %v", err)
+				output(CommandOutput{Success: false, Error: errMsg})
+				return errors.New(errMsg)
 			}
-			fmt.Println(t)
+			output(CommandOutput{Success: true, Token: t})
 			return nil
 		},
 	}

cmd/encode-rs.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 
 	"github.com/sgaunet/jwt-cli/pkg/cryptojwt"
@@ -53,9 +54,11 @@ Tip: Payload must be valid JSON. Common claims include 'sub' (subject), 'exp' (e
 			j := encoder(privateKeyFile)
 			t, err := j.Encode(payload)
 			if err != nil {
-				return fmt.Errorf("encoding failed: %w", err)
+				errMsg := fmt.Sprintf("encoding failed: %v", err)
+				output(CommandOutput{Success: false, Error: errMsg})
+				return errors.New(errMsg)
 			}
-			fmt.Println(t)
+			output(CommandOutput{Success: true, Token: t})
 			return nil
 		},
 	}

cmd/output.go

@@ -0,0 +1,67 @@
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+)
+
+// CommandOutput represents the structured output format for all commands.
+// It provides a consistent interface for both JSON and human-readable output modes.
+type CommandOutput struct {
+	// Success indicates whether the operation completed successfully
+	Success bool `json:"success"`
+
+	// Data holds generic output data (rarely used, reserved for future extensions)
+	Data any `json:"data,omitempty"`
+
+	// Claims holds the decoded JWT claims/payload
+	Claims any `json:"claims,omitempty"`
+
+	// Token holds the encoded JWT token string
+	Token string `json:"token,omitempty"`
+
+	// Error holds the error message if Success is false
+	Error string `json:"error,omitempty"`
+}
+
+// output writes the command result to stdout in either JSON or human-readable format.
+// In JSON mode, it always outputs valid JSON regardless of success/failure.
+// In human-readable mode, errors are written to stderr.
+// Note: This function does NOT call os.Exit(). Exit handling is done by the caller
+// through Cobra's error return mechanism and root.Execute().
+func output(out CommandOutput) {
+	if jsonOutput {
+		outputJSON(out)
+		return
+	}
+	outputHumanReadable(out)
+}
+
+// outputJSON writes the output in JSON format.
+func outputJSON(out CommandOutput) {
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	if err := enc.Encode(out); err != nil {
+		// This should never happen, but if JSON encoding fails, output a minimal error
+		fmt.Fprintf(os.Stderr, `{"success":false,"error":"failed to encode JSON output: %s"}`+"\n", err)
+	}
+}
+
+// outputHumanReadable writes the output in human-readable format.
+func outputHumanReadable(out CommandOutput) {
+	if out.Error != "" {
+		fmt.Fprintln(os.Stderr, out.Error)
+		return
+	}
+	if out.Token != "" {
+		fmt.Println(out.Token)
+	}
+	if out.Claims != nil {
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		if err := enc.Encode(out.Claims); err != nil {
+			fmt.Fprintf(os.Stderr, "failed to encode claims: %s\n", err)
+		}
+	}
+}

cmd/root.go

@@ -22,6 +22,9 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// jsonOutput controls whether to output in JSON format or human-readable format.
+var jsonOutput bool
+
 // rootCmd represents the base command when called without any subcommands.
 var rootCmd = &cobra.Command{
 	Use:   "jwt-cli",
@@ -46,6 +49,9 @@ Use RSA or ECDSA for scenarios requiring public/private key pairs.`,
 
   # Encode with RS256 using private key
   jwt-cli encode rs256 --payload '{"user":"alice"}' --private-key RS256.key`,
+	// Silence errors because the output() function already prints them appropriately
+	SilenceErrors: true,
+	SilenceUsage:  true,
 }
 
 // Execute runs the root command.
@@ -58,6 +64,9 @@ func Execute() {
 
 //nolint:funlen // init function requires many statements for command setup
 func init() {
+	// Global flags for all commands
+	rootCmd.PersistentFlags().BoolVar(&jsonOutput, "json", false, "output in JSON format")
+
 	rootCmd.AddCommand(encodeCmd)
 	rootCmd.CompletionOptions.DisableDefaultCmd = false
 	encodeCmd.PersistentFlags().StringP("payload", "p", "", "JSON payload to encode into JWT (e.g., '{\"user\":\"alice\"}')")