cli

Documentation

Overview

Package cli provides the command-line interface for the Neru application.

This package implements a comprehensive CLI using the Cobra framework that allows users to control the Neru daemon externally. The CLI serves as the primary interface for automation, scripting, and manual control of Neru's functionality.

Index

• Constants
• Variables
• func BuildActionCommand(use, short, long string, params []string) *cobra.Command
• func BuildSimpleCommand(use, short, long string, action string) *cobra.Command
• func Execute()
• func IsRunningFromAppBundle() bool

Constants

const (
	// DefaultIPCTimeoutSeconds is the default IPC timeout in seconds.
	DefaultIPCTimeoutSeconds = 5
)

Variables

var (

	// LaunchFunc is set by main to handle daemon launch.
	LaunchFunc func(configPath string)
	// Version is set via ldflags at build time.
	Version = "dev"
	// GitCommit is set via ldflags at build time.
	GitCommit = "unknown"
	// BuildDate is set via ldflags at build time.
	BuildDate = "unknown"
)

var ActionCmd = &cobra.Command{
	Use:   "action",
	Short: "Perform immediate mouse actions",
	Long:  `Perform immediate mouse actions at the current cursor position.`,
	PreRunE: func(cmd *cobra.Command, args []string) error {
		return requiresRunningInstance()
	},
	RunE: func(cmd *cobra.Command, args []string) error {
		return derrors.New(
			derrors.CodeInvalidInput,
			"action subcommand required (e.g., neru action left_click)",
		)
	},
}

ActionCmd is the CLI action command for performing immediate actions.

var ActionLeftClickCmd = BuildActionCommand(
	"left_click",
	"Perform left click at current cursor position",
	`Execute a left click at the current cursor location.`,
	[]string{"left_click"},
)

ActionLeftClickCmd is the left click action command.

var ActionMiddleClickCmd = BuildActionCommand(
	"middle_click",
	"Perform middle click at current cursor position",
	`Execute a middle click at the current cursor location.`,
	[]string{"middle_click"},
)

ActionMiddleClickCmd is the middle click action command.

var ActionMouseDownCmd = BuildActionCommand(
	"mouse_down",
	"Press mouse button at current cursor position",
	`Press and hold the left mouse button at the current cursor location.`,
	[]string{"mouse_down"},
)

ActionMouseDownCmd is the mouse down action command.

var ActionMouseUpCmd = BuildActionCommand(
	"mouse_up",
	"Release mouse button at current cursor position",
	`Release the left mouse button at the current cursor location.`,
	[]string{"mouse_up"},
)

ActionMouseUpCmd is the mouse up action command.

var ActionRightClickCmd = BuildActionCommand(
	"right_click",
	"Perform right click at current cursor position",
	`Execute a right click at the current cursor location.`,
	[]string{"right_click"},
)

ActionRightClickCmd is the right click action command.

var DoctorCmd = &cobra.Command{
	Use:   "doctor",
	Short: "Check the health of Neru components",
	RunE: func(cmd *cobra.Command, _ []string) error {
		communicator := cliutil.NewIPCCommunicator(timeoutSec)

		ipcResponse, err := communicator.SendCommand(domain.CommandHealth, []string{})
		if err != nil {
			return err
		}

		return formatter.PrintHealth(cmd, ipcResponse.Success, ipcResponse.Data)
	},
}

DoctorCmd is the CLI doctor command.

var GridCmd = &cobra.Command{
	Use:   "grid",
	Short: "Launch grid mode",
	Long:  `Activate grid mode for mouseless navigation.`,
	PreRunE: func(_ *cobra.Command, _ []string) error {
		return requiresRunningInstance()
	},
	RunE: func(cmd *cobra.Command, _ []string) error {
		action, err := cmd.Flags().GetString("action")
		if err != nil {
			return err
		}
		if action != "" {

			if !domain.IsKnownActionName(domain.ActionName(action)) {
				return derrors.Newf(
					derrors.CodeInvalidInput,
					"invalid action: %s. Supported actions: %s",
					action,
					domain.SupportedActionsString(),
				)
			}
		}

		var params []string
		params = append(params, "grid")
		if action != "" {
			params = append(params, action)
		}

		return sendCommand(cmd, "grid", params)
	},
}

GridCmd is the CLI grid command.

var HintsCmd = &cobra.Command{
	Use:   "hints",
	Short: "Launch hints mode",
	Long:  `Activate hint mode for direct clicking on UI elements.`,
	PreRunE: func(_ *cobra.Command, _ []string) error {
		return requiresRunningInstance()
	},
	RunE: func(cmd *cobra.Command, _ []string) error {
		action, err := cmd.Flags().GetString("action")
		if err != nil {
			return err
		}
		if action != "" {

			if !domain.IsKnownActionName(domain.ActionName(action)) {
				return derrors.Newf(
					derrors.CodeInvalidInput,
					"invalid action: %s. Supported actions: %s",
					action,
					domain.SupportedActionsString(),
				)
			}
		}

		var params []string
		params = append(params, "hints")
		if action != "" {
			params = append(params, action)
		}

		return sendCommand(cmd, "hints", params)
	},
}

HintsCmd is the CLI hints command.

var IdleCmd = &cobra.Command{
	Use:   "idle",
	Short: "Set mode to idle",
	Long:  `Exit the current mode and return to idle state.`,
	PreRunE: func(_ *cobra.Command, _ []string) error {
		return requiresRunningInstance()
	},
	RunE: func(cmd *cobra.Command, args []string) error {
		return sendCommand(cmd, "idle", args)
	},
}

IdleCmd is the CLI idle command.

var LaunchCmd = &cobra.Command{
	Use:   "launch",
	Short: "Launch the neru program",
	Long:  `Launch the neru program. Same as running 'neru' without any subcommand.`,
	RunE: func(cmd *cobra.Command, _ []string) error {
		launchProgram(cmd, configPath)

		return nil
	},
}

LaunchCmd is the CLI launch command.

var MetricsCmd = &cobra.Command{
	Use:   "metrics",
	Short: "Show application metrics",
	RunE: func(cmd *cobra.Command, _ []string) error {
		if !ipc.IsServerRunning() {
			cmd.Println("❌ Neru is not running")

			return nil
		}

		ipcClient := ipc.NewClient()
		ipcResponse, ipcResponseErr := ipcClient.Send(ipc.Command{Action: domain.CommandMetrics})
		if ipcResponseErr != nil {
			return derrors.Wrap(ipcResponseErr, derrors.CodeIPCFailed, "failed to get metrics")
		}

		if !ipcResponse.Success {
			return derrors.New(derrors.CodeIPCFailed, ipcResponse.Message)
		}

		if ipcResponse.Data == nil {
			cmd.Println("No metrics recorded yet")

			return nil
		}

		ipcResponseData, ipcResponseDataErr := json.Marshal(ipcResponse.Data)
		if ipcResponseDataErr != nil {
			return derrors.Wrap(
				ipcResponseDataErr,
				derrors.CodeSerializationFailed,
				"failed to marshal metrics data",
			)
		}

		var metrics []struct {
			Name  string  `json:"name"`
			Value float64 `json:"value"`
			Type  int     `json:"type"`
		}

		ipcResponseDataErr = json.Unmarshal(ipcResponseData, &metrics)
		if ipcResponseDataErr != nil {
			return derrors.Wrap(
				ipcResponseDataErr,
				derrors.CodeSerializationFailed,
				"failed to parse metrics",
			)
		}

		if len(metrics) == 0 {
			cmd.Println("No metrics recorded yet")

			return nil
		}

		sort.Slice(metrics, func(i, j int) bool {
			return metrics[i].Name < metrics[j].Name
		})

		cmd.Println("📊 Application Metrics:")
		cmd.Println("-----------------------")

		for _, metric := range metrics {
			switch metric.Type {
			case 0:
				cmd.Printf("%-40s %d\n", metric.Name, int(metric.Value))
			case 1:
				cmd.Printf("%-40s %.2f\n", metric.Name, metric.Value)
			default:
				cmd.Printf("%-40s %.4fs\n", metric.Name, metric.Value)
			}
		}

		cmd.Printf("\nLast updated: %s\n", time.Now().Format(time.RFC1123))

		return nil
	},
}

MetricsCmd is the CLI metrics command.

var ProfileCmd = &cobra.Command{
	Use:   "profile",
	Short: "Show profiling information",
	Long:  `Display information about enabling and accessing Go pprof profiling.`,
	RunE: func(cmd *cobra.Command, _ []string) error {
		cmd.Println("Neru Profiling:")
		cmd.Println("  To enable profiling, set the NERU_PPROF environment variable:")
		cmd.Println("    export NERU_PPROF=:6060")
		cmd.Println("  Then restart Neru:")
		cmd.Println("    neru stop && NERU_PPROF=:6060 neru launch")
		cmd.Println("  Access profiles at: http://localhost:6060/debug/pprof/")
		cmd.Println("  Heap profile: http://localhost:6060/debug/pprof/heap")
		cmd.Println("  CPU profile: http://localhost:6060/debug/pprof/profile?seconds=30")
		cmd.Println("  Use 'go tool pprof' to analyze profiles")

		return nil
	},
}

ProfileCmd is the CLI profile command.

var RootCmd = &cobra.Command{
	Use:   "neru",
	Short: "Neru - Keyboard-driven navigation for macOS",
	Long: `Neru is a keyboard-driven navigation tool for macOS that provides
vim-like navigation capabilities across all applications using accessibility APIs.`,
	Version: Version,
	RunE: func(cmd *cobra.Command, args []string) error {
		if IsRunningFromAppBundle() && len(args) == 0 {
			launchProgram(cmd, configPath)

			return nil
		}

		return cmd.Help()
	},
}

RootCmd is the root CLI command for Neru.

var ScrollCmd = &cobra.Command{
	Use:   "scroll",
	Short: "Launch scroll mode",
	Long:  `Activate scroll mode for vim-style scrolling at the cursor position.`,
	PreRunE: func(_ *cobra.Command, _ []string) error {
		return requiresRunningInstance()
	},
	RunE: func(cmd *cobra.Command, _ []string) error {
		return sendCommand(cmd, "scroll", []string{})
	},
}

ScrollCmd is the CLI scroll command.

var ServicesCmd = &cobra.Command{
	Use:   "services",
	Short: "Manage the neru launchd service",
	Long:  `Manage the neru launchd service for automatic startup.`,
}

ServicesCmd is the CLI services command for managing launchd service.

var ServicesInstallCmd = &cobra.Command{
	Use:   "install",
	Short: "Install and load the launchd service",
	Long:  `Install the launchd service by copying the plist to LaunchAgents and loading it.`,
	RunE: func(cmd *cobra.Command, args []string) error {
		err := installService()
		if err != nil {
			return err
		}
		cmd.Println("Service installed and loaded successfully")

		return nil
	},
}

ServicesInstallCmd is the CLI install subcommand.

var ServicesRestartCmd = &cobra.Command{
	Use:   "restart",
	Short: "Restart the launchd service",
	Long:  `Restart the neru launchd service.`,
	RunE: func(cmd *cobra.Command, args []string) error {
		err := restartService()
		if err != nil {
			return err
		}
		cmd.Println("Service restarted")

		return nil
	},
}

ServicesRestartCmd is the CLI restart subcommand.

var ServicesStartCmd = &cobra.Command{
	Use:   "start",
	Short: "Start the launchd service",
	Long:  `Start the neru launchd service.`,
	RunE: func(cmd *cobra.Command, args []string) error {
		err := startService()
		if err != nil {
			return err
		}
		cmd.Println("Service started")

		return nil
	},
}

ServicesStartCmd is the CLI start subcommand.

var ServicesStatusCmd = &cobra.Command{
	Use:   "status",
	Short: "Check the status of the launchd service",
	Long:  `Check if the neru launchd service is loaded and running.`,
	RunE: func(cmd *cobra.Command, args []string) error {
		cmd.Println(statusService())

		return nil
	},
}

ServicesStatusCmd is the CLI status subcommand.

var ServicesStopCmd = &cobra.Command{
	Use:   "stop",
	Short: "Stop the launchd service",
	Long:  `Stop the neru launchd service.`,
	RunE: func(cmd *cobra.Command, args []string) error {
		err := stopService()
		if err != nil {
			return err
		}
		cmd.Println("Service stopped")

		return nil
	},
}

ServicesStopCmd is the CLI stop subcommand.

var ServicesUninstallCmd = &cobra.Command{
	Use:   "uninstall",
	Short: "Unload and remove the launchd service",
	Long:  `Unload the launchd service and remove the plist from LaunchAgents.`,
	RunE: func(cmd *cobra.Command, args []string) error {
		err := uninstallService()
		if err != nil {
			return err
		}
		cmd.Println("Service uninstalled successfully")

		return nil
	},
}

ServicesUninstallCmd is the CLI uninstall subcommand.

var StartCmd = BuildSimpleCommand(
	"start",
	"Start the neru program (resume if paused)",
	`Start or resume the neru program. This enables neru if it was previously stopped.`,
	"start",
)

StartCmd is the CLI start command.

var StatusCmd = &cobra.Command{
	Use:   "status",
	Short: "Show neru status",
	Long:  `Display the current status of the neru program.`,
	PreRunE: func(_ *cobra.Command, _ []string) error {
		return requiresRunningInstance()
	},
	RunE: func(cmd *cobra.Command, _ []string) error {
		communicator := cliutil.NewIPCCommunicator(timeoutSec)

		ipcResponse, err := communicator.SendCommand("status", []string{})
		if err != nil {
			return err
		}

		if !ipcResponse.Success {
			return communicator.HandleResponse(cmd, ipcResponse)
		}

		return formatter.PrintStatus(cmd, ipcResponse.Data)
	},
}

StatusCmd is the CLI status command.

var StopCmd = BuildSimpleCommand(
	"stop",
	"Pause the neru program (does not quit)",
	`Pause the neru program. This disables neru functionality but keeps it running in the background.`,
	"stop",
)

StopCmd is the CLI stop command.

Functions

func BuildActionCommand

func BuildActionCommand(use, short, long string, params []string) *cobra.Command

BuildActionCommand creates an action cobra command with the given parameters.

func BuildSimpleCommand

func BuildSimpleCommand(use, short, long string, action string) *cobra.Command

BuildSimpleCommand creates a simple cobra command with the given parameters.

func Execute

func Execute()

Execute initializes and runs the CLI application.

func IsRunningFromAppBundle

func IsRunningFromAppBundle() bool

IsRunningFromAppBundle checks if the executable is running from a macOS app bundle.