CLI & Karabiner Integration

Control ovim from the terminal or integrate with Karabiner-Elements for custom key mappings and automation.

CLI commands

ovim includes a command-line tool for controlling modes from scripts or other applications. The CLI communicates with the running ovim app via a Unix socket.

Key	Action
`ovim mode`	Get current mode
`ovim toggle`	Toggle between insert and normal mode
`ovim insert`	Switch to insert mode (alias: i)
`ovim normal`	Switch to normal mode (alias: n)
`ovim visual`	Switch to visual mode (alias: v)
`ovim set <mode>`	Set mode to insert/normal/visual
`ovim edit`	Activate Edit Popup (alias: e)
`ovim click`	Activate Click Mode (alias: c)

Installation

The CLI is bundled with the ovim.app:

# Use directly from the app bundle
/Applications/ovim.app/Contents/MacOS/ovim toggle

# Or create a symlink for convenience
sudo ln -s /Applications/ovim.app/Contents/MacOS/ovim /usr/local/bin/ovim

Karabiner-Elements integration

Karabiner-Elements can execute shell commands via shell_command, making it easy to trigger ovim mode changes from custom key mappings.

Example: Caps Lock toggle

{
    "description": "Caps Lock toggles ovim mode",
    "manipulators": [
        {
            "type": "basic",
            "from": { "key_code": "caps_lock" },
            "to": [
                { "shell_command": "/Applications/ovim.app/Contents/MacOS/ovim toggle" }
            ]
        }
    ]
}

Example: Escape enters Normal mode

Enter normal mode when pressing Escape, excluding terminal apps:

{
    "description": "Escape enters ovim normal mode",
    "manipulators": [
        {
            "conditions": [
                {
                    "bundle_identifiers": [
                        "^com\\.apple\\.Terminal$",
                        "^com\\.googlecode\\.iterm2$",
                        "^net\\.kovidgoyal\\.kitty$"
                    ],
                    "type": "frontmost_application_unless"
                }
            ],
            "type": "basic",
            "from": { "key_code": "escape" },
            "to": [
                { "shell_command": "/Applications/ovim.app/Contents/MacOS/ovim normal" }
            ]
        }
    ]
}

Example: Mouse click enters Insert mode

Automatically enter insert mode when clicking:

{
    "description": "Mouse click enters ovim insert mode",
    "manipulators": [
        {
            "type": "basic",
            "from": { "any": "pointing_button" },
            "to": [
                { "shell_command": "/Applications/ovim.app/Contents/MacOS/ovim insert" },
                { "pointing_button": "button1" }
            ]
        }
    ]
}

Tips

The CLI returns immediately after sending the command; it does not wait for mode change confirmation
If ovim is not running, the CLI prints an error and exits with code 1
You can check the current mode with ovim mode in scripts