node-hyprctl

A TypeScript/Node.js wrapper for hyprctl, the command-line utility for controlling the Hyprland Wayland compositor.

Installation

npm install node-hyprctl

Features

• 🎯 Type-safe - Full TypeScript support with comprehensive type definitions
• 🚀 Easy to use - Simple, intuitive API mirroring hyprctl commands
• 📡 Event listening - Real-time event monitoring via Hyprland's socket
• 🔄 Auto JSON parsing - Automatic JSON parsing for all supported commands

Requirements

• Node.js (ESM support required)
• Hyprland compositor running on your system
• hyprctl command available in PATH

Usage

Basic Example

import Hyprctl from 'node-hyprctl'

// Get active window
const activeWindow = Hyprctl.activewindow()
console.log(`Active window: ${activeWindow.title}`)

// Get all clients (windows)
const clients = Hyprctl.clients()
console.log(`Total windows: ${clients.length}`)

// Get active workspace
const workspace = Hyprctl.activeworkspace()
console.log(`Current workspace: ${workspace.name}`)

// Dispatch commands
Hyprctl.dispatch('workspace', '1')
Hyprctl.dispatch('movetoworkspace', '2')

Event Listening

Listen to Hyprland events in real-time:

import Hyprctl from 'node-hyprctl'

const client = Hyprctl.listen()
client.on('activewindow', (activeWindow) => {
    console.log('Active window changed to:', activeWindow)
})

client.on('event', (event) => {
    console.log('Event received:', event)
})

API Reference

Window Management

activewindow(): Window

Get the currently active window.

const window = Hyprctl.activewindow()
console.log(window.title, window.class)

clients(): Array<Window>

Get all windows/clients.

const windows = Hyprctl.clients()
windows.forEach(w => console.log(w.title))

Workspace Management

activeworkspace(): Workspace

Get the currently active workspace.

workspaces(): Array<Workspace>

Get all workspaces.

workspacerules(): Array<WorkspaceRule>

Get all workspace rules.

Monitors

monitors(): Array<Monitor>

Get all monitors and their properties.

const monitors = Hyprctl.monitors()
monitors.forEach(m => {
  console.log(`${m.name}: ${m.width}x${m.height}@${m.refreshRate}Hz`)
})

System Information

version(): Version

Get Hyprland version information.

systeminfo(): string

Get detailed system information.

instances(): Array<Instance>

Get all running Hyprland instances.

Configuration

binds(): Array<Bind>

Get all keybindings.

animations(): [Array<Animation>, Array<AnimationBezier>]

Get animation settings and bezier curves.

configerrors(): Array<string>

Get configuration errors.

getoption(option: string): string

Get a specific configuration option value.

keyword(name: string, value: string): any

Set a configuration keyword dynamically.

Hyprctl.keyword('general:gaps_in', '5')

Devices

devices(): Device

Get all input devices (keyboards, mice, tablets, etc.).

cursorpos(): CursorPos

Get current cursor position.

const pos = Hyprctl.cursorpos()
console.log(`Cursor at: ${pos.x}, ${pos.y}`)

Dispatchers

dispatch(eventName: string, ...params: string[]): any | string

Execute hyprctl dispatch commands.

// Switch workspace
Hyprctl.dispatch('workspace', '1')

// Move window to workspace
Hyprctl.dispatch('movetoworkspace', '2')

// Toggle floating
Hyprctl.dispatch('togglefloating')

// Execute command
Hyprctl.dispatch('exec', 'kitty')

// Focus window
Hyprctl.dispatch('focuswindow', 'class:firefox')

Notifications

notify(options: { icon?: string, timeout?: number, color?: string, message: string }): string

Display a notification.

Hyprctl.notify({
  message: 'Hello from node-hyprctl!',
  timeout: 3000,
  color: 'rgb(ff6b6b)'
})

dismissnotify(amount?: number): string

Dismiss notifications.

Layers

layers(): Layers

Get layer information.

layouts(): Array<string>

Get available layouts.

Shortcuts

globalshortcuts(): Array<Shortcut>

Get global shortcuts.

Utilities

reload(config_only?: boolean): string

Reload Hyprland configuration.

Hyprctl.reload()        // Full reload
Hyprctl.reload(true)    // Config only

kill()

Kill the active window (use with cursor to select).

setcursor(theme: string, size: number): string

Set cursor theme and size.

switchxkblayout(device: string, cmd: string): string

Switch keyboard layout.

splash(): string

Get the current splash text.

rollinglog(): Array<string>

Get rolling log entries.

Event Listener

listen(instance_signature?: string): EventEmitter

Start listening to Hyprland events. Returns an EventEmitter that emits various Hyprland events.

const emitter = Hyprctl.listen()

TypeScript Types

The library exports comprehensive TypeScript types:

import type { 
  Window, 
  Workspace, 
  Monitor, 
  Animation,
  Bind,
  Device,
  Instance,
  Version,
  // ... and more
} from 'node-hyprctl'

Examples

Get window under cursor and close it

import Hyprctl from 'node-hyprctl'

// get cursor position
const cursorPosition = Hyprctl.cursorpos()
// get current workspace
const currentWorkspace = Hyprctl.activeworkspace()
// get all windows
const allWindows = Hyprctl.clients()

// loop through all windows to find which one is under the cursor and on the current workspace
const windowUnderCursor = allWindows.find(win => {
    const [x, y] = win.at
    const [w, h] = win.size
    return  cursorPosition.x >= x && 
            cursorPosition.x <= x + w && 
            cursorPosition.y >= y && 
            cursorPosition.y <= y + h &&
            win.workspace.id == currentWorkspace.id
})

// if no window found under cursor, exit
if(!windowUnderCursor) {
    console.log('No window found under cursor')
    process.exit(0)
}

// close the window found under cursor
Hyprctl.dispatch('closewindow', `address:${windowUnderCursor.address}`)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC

Author

Dimitri Gigot

Repository

https://github.com/dimitri-gigot/node-hyprctl

Related

• Hyprland - Dynamic tiling Wayland compositor
• hyprctl documentation - Official hyprctl documentation