Add LLM-friendly CLI features

- Add info command with --test-permissions flag for diagnostics
- Add structured API errors with categories and hints
- Add --quiet and --json-errors global flags
- Add auto-update notifications with 24h cache
- Add help footer with documentation links
- Enhance config command with detailed help text
- Update README with LLM section, exit codes, and troubleshooting
- Standardize exit codes: 0=success, 1=user error, 2=system error

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: nerveband

README.md

@@ -70,6 +70,35 @@ api_url: http://localhost:39867
 output_format: json  # json, text, markdown
 ```
 
+### Configuration Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `api_url` | string | `http://localhost:39867` | Beeper Desktop API endpoint URL |
+| `output_format` | string | `json` | Default output format: `json`, `text`, or `markdown` |
+
+### Environment Variables
+
+Environment variables override config file settings:
+
+| Variable | Description |
+|----------|-------------|
+| `BEEPER_API_URL` | Override API URL |
+| `BEEPER_OUTPUT_FORMAT` | Override output format |
+| `BEEPER_TOKEN` | API authentication token (required for most operations) |
+
+### Authentication
+
+Generate an API token in Beeper Desktop settings and set it as an environment variable:
+
+```bash
+export BEEPER_TOKEN="your-token-here"
+```
+
+Token permissions:
+- **read**: Access messages, chats, and accounts
+- **write**: Send messages, archive chats, set reminders
+
 ## API Coverage
 
 ### Read Operations
@@ -201,6 +230,66 @@ go test ./...
 ./build.sh
 ```
 
+## For LLMs and Automated Agents
+
+This CLI is designed for programmatic access by LLMs and automation tools.
+
+### Recommended Workflow
+
+1. **Check connectivity**: `beeper info` to verify API is reachable
+2. **Test permissions**: `beeper info --test-permissions` to verify token works
+3. **List chats**: `beeper chats list -o json` to get available chat IDs
+4. **Read messages**: `beeper messages list --chat-id <ID> -o json`
+5. **Send messages**: `beeper send --chat-id <ID> --message "text"`
+
+### Error Handling
+
+Use `--json-errors` for machine-readable error output:
+
+```bash
+beeper chats list --json-errors 2>&1
+```
+
+Error JSON format:
+```json
+{
+  "error": "error message",
+  "code": "error_code",
+  "category": "auth|config|permission|not_found|network|validation|server|unknown",
+  "operation": "operation_name",
+  "hint": "actionable suggestion"
+}
+```
+
+### Updating
+
+The CLI checks for updates automatically and notifies when a new version is available. To upgrade:
+
+```bash
+beeper upgrade
+```
+
+Use `--quiet` to suppress update notifications in automated environments.
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "connection refused" | Start Beeper Desktop and enable API |
+| "unauthorized" | Set `BEEPER_TOKEN` environment variable |
+| "not found" | Verify chat/message ID with `beeper chats list` |
+| "timeout" | Check network, restart Beeper Desktop |
+
+Run `beeper info` for diagnostic information.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | User/Application error (invalid arguments, missing resources, permission denied) |
+| 2 | System/Network error (connection failed, timeout, server error) |
+
 ## Requirements
 
 - Beeper Desktop application installed and running

cmd/config.go

@@ -10,14 +10,35 @@ import (
 var configCmd = &cobra.Command{
 	Use:   "config",
 	Short: "Manage configuration",
-	Long:  `View and modify Beeper CLI configuration settings.`,
+	Long: `View and modify Beeper CLI configuration settings.
+
+Configuration File:
+  Location: ~/.beeper-api-cli/config.yaml
+
+Configuration Fields:
+  api_url        The Beeper Desktop API URL (default: http://localhost:39867)
+  output_format  Default output format: json, text, or markdown (default: json)
+
+Environment Variables (override config file):
+  BEEPER_API_URL        Override api_url
+  BEEPER_OUTPUT_FORMAT  Override output_format
+  BEEPER_TOKEN          API authentication token (required for most operations)
+
+Example config.yaml:
+  api_url: http://localhost:39867
+  output_format: json
+
+Manual Editing:
+  You can edit the config file directly with any text editor.
+  Changes take effect on the next command execution.`,
 }
 
 var configShowCmd = &cobra.Command{
 	Use:   "show",
 	Short: "Display current configuration",
 	RunE: func(cmd *cobra.Command, args []string) error {
-		fmt.Printf("API URL: %s\n", cfg.APIURL)
+		fmt.Printf("Config File:   %s\n", config.GetConfigPath())
+		fmt.Printf("API URL:       %s\n", cfg.APIURL)
 		fmt.Printf("Output Format: %s\n", cfg.OutputFormat)
 		return nil
 	},

cmd/errors.go

@@ -0,0 +1,145 @@
+package cmd
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/nerveband/beeper-api-cli/internal/api"
+)
+
+// JSONError represents an error in JSON format for --json-errors output
+type JSONError struct {
+	Error     string `json:"error"`
+	Code      string `json:"code,omitempty"`
+	Category  string `json:"category,omitempty"`
+	Operation string `json:"operation,omitempty"`
+	Hint      string `json:"hint,omitempty"`
+}
+
+// formatError formats an error for display, adding hints if available
+func formatError(err error) string {
+	var apiErr *api.APIError
+	if errors.As(err, &apiErr) {
+		var sb strings.Builder
+		sb.WriteString("Error: ")
+		sb.WriteString(apiErr.Message)
+		sb.WriteString("\n")
+
+		if apiErr.Hint != "" && !quietMode {
+			sb.WriteString("\nHint: ")
+			sb.WriteString(apiErr.Hint)
+			sb.WriteString("\n")
+		}
+
+		return sb.String()
+	}
+
+	// For non-API errors, try to provide helpful hints based on error content
+	errMsg := err.Error()
+	hint := getGenericHint(errMsg)
+
+	if hint != "" && !quietMode {
+		return fmt.Sprintf("Error: %s\n\nHint: %s\n", errMsg, hint)
+	}
+
+	return fmt.Sprintf("Error: %s\n", errMsg)
+}
+
+// formatErrorAsJSON formats an error as JSON for --json-errors output
+func formatErrorAsJSON(err error) string {
+	jsonErr := JSONError{}
+
+	var apiErr *api.APIError
+	if errors.As(err, &apiErr) {
+		jsonErr.Error = apiErr.Message
+		jsonErr.Code = apiErr.Code
+		jsonErr.Category = string(apiErr.Category)
+		jsonErr.Operation = apiErr.Operation
+		jsonErr.Hint = apiErr.Hint
+	} else {
+		jsonErr.Error = err.Error()
+		jsonErr.Category = "unknown"
+		jsonErr.Hint = getGenericHint(err.Error())
+	}
+
+	data, _ := json.Marshal(jsonErr)
+	return string(data)
+}
+
+// getGenericHint returns a hint based on common error patterns
+func getGenericHint(errMsg string) string {
+	errLower := strings.ToLower(errMsg)
+
+	switch {
+	case strings.Contains(errLower, "connection refused"):
+		return "Beeper Desktop may not be running. Start Beeper Desktop and ensure the API is enabled."
+	case strings.Contains(errLower, "no such host"):
+		return "Could not resolve the API host. Check your network connection and API URL configuration."
+	case strings.Contains(errLower, "timeout"):
+		return "The request timed out. Check if Beeper Desktop is responding and your network is stable."
+	case strings.Contains(errLower, "unauthorized") || strings.Contains(errLower, "401"):
+		return "Authentication required. Set BEEPER_TOKEN environment variable with a valid API token."
+	case strings.Contains(errLower, "forbidden") || strings.Contains(errLower, "403"):
+		return "Access denied. Your token may lack the required permissions."
+	case strings.Contains(errLower, "not found") || strings.Contains(errLower, "404"):
+		return "Resource not found. Verify the ID is correct using 'beeper chats list'."
+	case strings.Contains(errLower, "config"):
+		return "Configuration error. Check your settings with 'beeper config show'."
+	default:
+		return ""
+	}
+}
+
+// handleError processes an error and exits with appropriate code
+// Returns the exit code (for testing purposes)
+func handleError(err error) int {
+	if err == nil {
+		return 0
+	}
+
+	// Determine exit code based on error type
+	exitCode := 1 // Default: user/application error
+
+	var apiErr *api.APIError
+	if errors.As(err, &apiErr) {
+		switch apiErr.Category {
+		case api.CategoryNetwork:
+			exitCode = 2 // System/network error
+		case api.CategoryServer:
+			exitCode = 2 // Server error (system)
+		}
+	} else {
+		// Check for network-related errors in message
+		errMsg := strings.ToLower(err.Error())
+		if strings.Contains(errMsg, "connection refused") ||
+			strings.Contains(errMsg, "no such host") ||
+			strings.Contains(errMsg, "timeout") {
+			exitCode = 2
+		}
+	}
+
+	// Output error
+	if jsonErrors {
+		fmt.Fprintln(os.Stderr, formatErrorAsJSON(err))
+	} else {
+		fmt.Fprint(os.Stderr, formatError(err))
+	}
+
+	return exitCode
+}
+
+// exitWithError handles an error and exits the process
+func exitWithError(err error) {
+	code := handleError(err)
+	os.Exit(code)
+}
+
+// ExitCodes documents the exit codes used by the CLI
+var ExitCodes = map[int]string{
+	0: "Success",
+	1: "User/Application error (invalid arguments, missing resources, permission denied)",
+	2: "System/Network error (connection failed, timeout, server error)",
+}