Input

bolt

Native platform provider for mouse, keyboard, screen capture, and window management.

Overview

The @nut-tree/bolt package is an alternative low-level provider for nut.js that replaces default providers like @nut-tree/libnut with enhanced functionality. It provides proper unicode support, window finding by title, advanced window operations (minimize, restore, resize, move), and input monitoring for mouse and keyboard events.

Native I/O

Mouse, keyboard, and screen capture at the OS level

useBolt()

Window Management

Find, minimize, restore, resize, and move windows

windowWithTitle(/regex/)

Input Monitoring

Non-intrusive mouse and keyboard event monitoring

system.startMonitoringInputEvents()

Installation

typescript

npm i @nut-tree/bolt

Subscription Required

This package is included in Solo and Team subscription plans.

Quick Reference

bolt exports individual provider functions and a convenience useBolt() function that activates all providers at once:

useBolt

useBolt()

void

Activate all bolt providers (keyboard, mouse, screen, windows, window finder)

useBoltKeyboard

useBoltKeyboard()

void

Activate the bolt keyboard provider

useBoltMouse

useBoltMouse()

void

Activate the bolt mouse provider

useBoltScreen

useBoltScreen()

void

Activate the bolt screen provider

useBoltWindows

useBoltWindows()

void

Activate the bolt window management provider

useBoltWindowFinder

useBoltWindowFinder()

void

Activate the bolt window finder provider

useBoltInputMonitor

useBoltInputMonitor()

void

Activate the bolt input monitoring provider

Usage

Individual Providers

Activate only the providers you need:

typescript

import { keyboard } from "@nut-tree/nut-js";
import { useBoltKeyboard } from "@nut-tree/bolt";

useBoltKeyboard();

await keyboard.type("@nut-tree/bolt is awesome!");

All Providers

Use useBolt() to activate all providers at once:

typescript

import { screen, windowWithTitle } from "@nut-tree/nut-js";
import { useBolt } from "@nut-tree/bolt";

useBolt();

const wnd = await screen.find(windowWithTitle(/some.*regex/));

Input Monitoring

bolt provides non-intrusive input monitoring that observes mouse and keyboard events without interfering with system functionality. The mouse and keyboard instances act as EventEmitters, letting you register listeners for input events:

typescript

import { mouse, keyboard, system, Key } from "@nut-tree/nut-js";
import { useBoltInputMonitor, isKeyEvent, withModifiers } from "@nut-tree/bolt";

useBoltInputMonitor();

keyboard.on("keyDown", async (evt) => {
    if (isKeyEvent(evt, Key.Escape) && withModifiers(evt, [Key.LeftControl])) {
        system.stopMonitoringInputEvents();
    }
});

mouse.on("mouseDown", async (evt) => {
    console.log(`Button ${evt.button} at ${evt.targetPoint.x}, ${evt.targetPoint.y}`);
});

system.startMonitoringInputEvents();

Platform Support

Input monitoring is available on Windows and macOS.

Best Practices

Initialization

Call useBolt() early in your application, before any nut.js operations. It only needs to be called once.

Permissions

macOS: Requires Accessibility and Screen Recording permissions in System Settings
Linux: May require additional packages depending on features used
Windows: No special permissions needed for most features

Mouse Control

Full mouse control documentation

Keyboard Input

Full keyboard input documentation

Window Management

Full window management documentation