Introduction

Getting Started

Get up and running with nut.js in minutes. This guide will walk you through installation, basic setup, and your first automation script.

Installation

Install nut.js and its dependencies

Core Concepts

Learn the fundamentals of desktop automation

API Reference

Explore the complete API documentation

Quick Start

Follow these steps to create your first nut.js automation script.

Step 1: Install nut.js

Install nut.js using your preferred package manager. The prebuilt packages mean no native compilation is required.

npm install @nut-tree/nut-js

Step 2: Create your script

Create a new file called automation.ts and add the following code:

automation.ts

import { mouse, keyboard, screen, straightTo, Point } from "@nut-tree/nut-js";

// Move mouse to center of screen
const screenWidth = await screen.width();
const screenHeight = await screen.height();

await mouse.move(straightTo(new Point(screenWidth / 2, screenHeight / 2)));

// Type some text
await keyboard.type("Hello from nut.js!");

Step 3: Run your script

Execute your automation script using Node.js or a TypeScript runner like tsx:

shell

npx tsx automation.ts

Permissions Required

On macOS, you'll need to grant accessibility permissions to your terminal application. Go to System Preferences → Security & Privacy → Privacy → Accessibility.

Pro Tip

For TypeScript projects, you can also use ts-node or compile your code with tsc before running with Node.js.

Next Steps

Now that you have nut.js running, explore these topics to learn more:

Mouse Control — Learn about precise mouse movements, clicks, and drags
Keyboard Input — Type text and simulate key combinations
Screen & Image Search — Find UI elements and capture screenshots
Window Management — Control application windows