Add --payload-file flag to kernel invoke (#66)

## Summary

Add a `--payload-file` / `-f` flag to `kernel invoke` that allows
reading the JSON payload from a file instead of passing it inline. This
is useful for:

- Large payloads that are unwieldy on the command line
- Payloads with special characters that need escaping
- Scripting and automation workflows
- Piping data from other commands

## Usage

```bash
# Read payload from a file
kernel invoke myapp action -f payload.json

# Read payload from stdin
cat payload.json | kernel invoke myapp action -f -

# Pipe from another command
echo '{"key": "value"}' | kernel invoke myapp action -f -

# Combine with other tools
jq '.data' response.json | kernel invoke myapp process -f -
```

## Details

- The `--payload` and `--payload-file` flags are mutually exclusive
(enforced by cobra)
- Supports `-` as a special filename to read from stdin
- Validates that the file contents are valid JSON before invoking
- Trims whitespace from file contents

## Test plan

- [x] `go build ./...` passes
- [x] `go test ./...` passes
- [x] Help output shows new flag correctly
- [ ] Manual test: `kernel invoke app action -f payload.json`
- [ ] Manual test: `echo '{}' | kernel invoke app action -f -`
- [ ] Manual test: verify `--payload` and `--payload-file` cannot be
used together

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds file/stdin-based payload input to `kernel invoke` with JSON
validation and updates docs.
> 
> - Introduces `--payload-file`, `-f` flag in `invoke` (mutually
exclusive with `--payload`)
> - New `getPayload` helper supports reading from file or `-` (stdin),
trims whitespace, and validates JSON before invoking
> - Wires payload into invocation params when provided; preserves
existing sync/async behavior
> - README updated with new flag in command reference and examples for
file/stdin/pipe usage
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
d7205d5. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: rgarcia

README.md

@@ -150,6 +150,7 @@ Create an API key from the [Kernel dashboard](https://dashboard.onkernel.com).
 
   - `--version <version>`, `-v` - Specify app version (default: latest)
   - `--payload <json>`, `-p` - JSON payload for the action
+  - `--payload-file <path>`, `-f` - Read JSON payload from a file (use `-` for stdin)
   - `--sync`, `-s` - Invoke synchronously (timeout after 60s)
 
 - `kernel app list` - List deployed apps
@@ -423,6 +424,15 @@ kernel invoke my-scraper scrape-page
 # With JSON payload
 kernel invoke my-scraper scrape-page --payload '{"url": "https://example.com"}'
 
+# Read payload from a file
+kernel invoke my-scraper scrape-page --payload-file payload.json
+
+# Read payload from stdin
+cat payload.json | kernel invoke my-scraper scrape-page --payload-file -
+
+# Pipe from another command
+echo '{"url": "https://example.com"}' | kernel invoke my-scraper scrape-page -f -
+
 # Synchronous invoke (wait for completion)
 kernel invoke my-scraper quick-task --sync
 ```

cmd/invoke.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	"os"
 	"os/signal"
 	"strings"
@@ -37,7 +38,9 @@ var invocationHistoryCmd = &cobra.Command{
 func init() {
 	invokeCmd.Flags().StringP("version", "v", "latest", "Specify a version of the app to invoke (optional, defaults to 'latest')")
 	invokeCmd.Flags().StringP("payload", "p", "", "JSON payload for the invocation (optional)")
+	invokeCmd.Flags().StringP("payload-file", "f", "", "Path to a JSON file containing the payload (use '-' for stdin)")
 	invokeCmd.Flags().BoolP("sync", "s", false, "Invoke synchronously (default false). A synchronous invocation will open a long-lived HTTP POST to the Kernel API to wait for the invocation to complete. This will time out after 60 seconds, so only use this option if you expect your invocation to complete in less than 60 seconds. The default is to invoke asynchronously, in which case the CLI will open an SSE connection to the Kernel API after submitting the invocation and wait for the invocation to complete.")
+	invokeCmd.MarkFlagsMutuallyExclusive("payload", "payload-file")
 
 	invocationHistoryCmd.Flags().Int("limit", 100, "Max invocations to return (default 100)")
 	invocationHistoryCmd.Flags().StringP("app", "a", "", "Filter by app name")
@@ -65,15 +68,11 @@ func runInvoke(cmd *cobra.Command, args []string) error {
 		Async:      kernel.Opt(!isSync),
 	}
 
-	payloadStr, _ := cmd.Flags().GetString("payload")
-	if cmd.Flags().Changed("payload") {
-		// validate JSON unless empty string explicitly set
-		if payloadStr != "" {
-			var v interface{}
-			if err := json.Unmarshal([]byte(payloadStr), &v); err != nil {
-				return fmt.Errorf("invalid JSON payload: %w", err)
-			}
-		}
+	payloadStr, hasPayload, err := getPayload(cmd)
+	if err != nil {
+		return err
+	}
+	if hasPayload {
 		params.Payload = kernel.Opt(payloadStr)
 	}
 	// we don't really care to cancel the context, we just want to handle signals
@@ -218,6 +217,58 @@ func printResult(success bool, output string) {
 	}
 }
 
+// getPayload reads the payload from either --payload flag or --payload-file flag.
+// Returns the payload string, whether a payload was explicitly provided, and any error.
+// The second return value (hasPayload) is true when the user explicitly set a payload,
+// even if that payload is an empty string.
+func getPayload(cmd *cobra.Command) (payload string, hasPayload bool, err error) {
+	payloadStr, _ := cmd.Flags().GetString("payload")
+	payloadFile, _ := cmd.Flags().GetString("payload-file")
+
+	// If --payload was explicitly set, use it (even if empty string)
+	if cmd.Flags().Changed("payload") {
+		// Validate JSON unless empty string explicitly set
+		if payloadStr != "" {
+			var v interface{}
+			if err := json.Unmarshal([]byte(payloadStr), &v); err != nil {
+				return "", false, fmt.Errorf("invalid JSON payload: %w", err)
+			}
+		}
+		return payloadStr, true, nil
+	}
+
+	// If --payload-file was set, read from file
+	if cmd.Flags().Changed("payload-file") {
+		var data []byte
+
+		if payloadFile == "-" {
+			// Read from stdin
+			data, err = io.ReadAll(os.Stdin)
+			if err != nil {
+				return "", false, fmt.Errorf("failed to read payload from stdin: %w", err)
+			}
+		} else {
+			// Read from file
+			data, err = os.ReadFile(payloadFile)
+			if err != nil {
+				return "", false, fmt.Errorf("failed to read payload file: %w", err)
+			}
+		}
+
+		payloadStr = strings.TrimSpace(string(data))
+		// Validate JSON unless empty
+		if payloadStr != "" {
+			var v interface{}
+			if err := json.Unmarshal([]byte(payloadStr), &v); err != nil {
+				return "", false, fmt.Errorf("invalid JSON in payload file: %w", err)
+			}
+		}
+		return payloadStr, true, nil
+	}
+
+	return "", false, nil
+}
+
 func runInvocationHistory(cmd *cobra.Command, args []string) error {
 	client := getKernelClient(cmd)