feat(cli): implement headless JSON-RPC interactivity protocol

README.md

@@ -102,6 +102,14 @@ Export cheat metadata as JSON or CSV for indexing and tooling:
 cheatmd dump ~/cheats --json
 ```
 
+### Headless Mode
+
+Run CheatMD without a TUI to integrate with other tools (like VS Code or Obsidian) using a JSON-RPC interface over standard I/O:
+
+```bash
+cheatmd --headless -q "docker exec"
+```
+
 ## TUI Keys
 
 | Key | Action |
@@ -127,6 +135,7 @@ Full documentation lives in the **[Wiki](../../wiki)**:
 - **[Shell Integration](../../wiki/Shell-Integration)** - widget, tmux, zellij
 - **[Linting](../../wiki/Linting)** - syntax and reference validation
 - **[Dump](../../wiki/Dump)** - metadata export
+- **[Headless Mode](../../wiki/Headless-Mode)** - JSON-RPC programmatic interface
 - **[Recipes](../../wiki/Recipes)** - copy-pasteable patterns
 
 ## Contributing

cmd/cheatmd/root.go

@@ -7,6 +7,7 @@ import (
 	"runtime"
 	"time"
 
+	"github.com/gubarz/cheatmd/internal/headless"
 	"github.com/gubarz/cheatmd/internal/ui"
 	"github.com/gubarz/cheatmd/pkg/config"
 	"github.com/gubarz/cheatmd/pkg/executor"
@@ -36,6 +37,7 @@ func init() {
 	chainCmd.AddCommand(chainResetCmd)
 
 	rootCmd.PersistentFlags().StringP("query", "q", "", "Initial search query")
+	rootCmd.PersistentFlags().Bool("headless", false, "Run in headless interactive JSON-RPC mode")
 	rootCmd.PersistentFlags().StringP("match", "m", "", "Match a full command pattern and auto-fill its variables")
 	rootCmd.PersistentFlags().BoolP("print", "p", false, "Print command (default)")
 	rootCmd.PersistentFlags().BoolP("copy", "c", false, "Copy command")
@@ -140,6 +142,11 @@ func runCheats(cmd *cobra.Command, args []string) error {
 		return nil
 	}
 
+	headlessFlag, _ := cmd.Flags().GetBool("headless")
+	if headlessFlag {
+		return headless.Run(index, exec, query, match)
+	}
+
 	// Run the TUI (history view if --history was passed)
 	var finalCmd string
 	if historyFlag, _ := cmd.Flags().GetBool("history"); historyFlag {