API Reference

API Reference

NUTClient

High-level client facade with auto-reconnect, tracking, and typed parsing.

Constructor

new NUTClient(host: string, port?: number, options?: INUTClientOptions)

Parameter	Type	Default	Description
host	string	—	Hostname or IP of the NUT server
port	number	3493	NUT server port
options	INUTClientOptions	—	Client options

INUTClientOptions

Extends IRawNUTClientOptions (timeout and connectTimeout).

interface INUTClientOptions {
  timeout?: number;              // default timeout for commands (ms). No timeout if not set or Infinity.
  connectTimeout?: number;       // timeout for TCP connection (ms), default: 10000
  autoReconnect?: boolean;       // enable auto-reconnect, default: false
  reconnectDelay?: number;       // initial reconnect delay (ms), default: 1000
  maxReconnectDelay?: number;    // max delay for exponential backoff (ms), default: 30000
  reconnectBackoff?: number;     // backoff multiplier, default: 2
  maxReconnectAttempts?: number; // max attempts before giving up, default: Infinity
  username?: string;             // stored and re-sent on reconnect
  password?: string;             // stored and re-sent on reconnect
}

Static Factory

static async create(host, port?, options?): Promise<NUTClient>

Creates a client and optionally authenticates. Credentials are cleared from the options object after successful authentication (but stored internally for reconnect).

Properties

Property	Type	Description
connected	boolean (getter)	Whether the client is currently connected

Core Methods

Method	Returns	Description
connect(username, password)	Promise<void>	Authenticate with the NUT server
logout()	Promise<string>	Log out from the server
version()	Promise<string>	Get NUT server version
netVersion()	Promise<string>	Get network protocol version
help()	Promise<string>	Get available commands
startTLS(options?)	Promise<void>	Upgrade connection to TLS
send(cmd: string[], timeout?)	Promise<string>	Send raw NUT command
destroy()	void	Destroy client and release resources

UPS Methods

Method	Returns	Description
listUPS()	Promise<UPS[]>	List all UPS devices
getUPS(name)	Promise<UPS | undefined>	Get a UPS by name
getUPSDescription(ups)	Promise<string>	Get UPS description (from ups.conf desc=)
listVariables(ups)	Promise<nutVariables>	List all variables as key-value object
listWriteableVariables(ups)	Promise<Record<string, string>>	List read-write variables
listCommands(ups)	Promise<string[]>	List instant commands
listClients(ups)	Promise<string[]>	List connected clients
getNumLogins(ups)	Promise<number>	Get count of logged-in clients

Variable Methods

Method	Returns	Description
getVariable(ups, variable)	Promise<string>	Get variable value
setVariable(ups, variable, value, options?)	Promise<CommandResult | TrackedResult>	Set variable value
getVariableType(ups, variable)	Promise<string>	Get variable type
getVariableDescription(ups, variable)	Promise<string>	Get variable description
getVariableEnum(ups, variable)	Promise<string[]>	Get valid enum values
getVariableRange(ups, variable)	Promise<string[]>	Get valid range

Command Methods

Method	Returns	Description
runCommand(ups, command, param?, options?)	Promise<CommandResult | TrackedResult>	Run instant command
getCommandDescription(ups, command)	Promise<string>	Get command description
forceShutdown(ups)	Promise<string>	Force shutdown (set FSD flag). Requires master/FSD permission

Tracking Methods

Method	Returns	Description
setTracking(enabled)	Promise<void>	Enable/disable command tracking (NUT 2.8.0+)
getTracking(uuid)	Promise<'PENDING' | 'SUCCESS' | 'ERR'>	Poll tracking status

Session Methods

Method	Returns	Description
login(ups)	Promise<string>	Login to a UPS (for upsmon use)
master(ups)	Promise<string>	Claim master status
getMaster(ups)	Promise<boolean>	Check if master

Events

Event	Arguments	Description
disconnected	—	Connection lost
reconnecting	(attempt, delay)	Reconnect attempt scheduled
reconnected	—	Connection re-established
reconnectFailed	(attempt)	Reconnect attempt failed
reconnectExhausted	—	Max attempts reached
destroyed	—	Client destroyed

---

UPS

Typed representation of a UPS device with convenience methods.

Properties

Property	Type	Description
name	string	UPS name
description	string	UPS description

Convenience Methods

Method	Returns	Description
getStatus()	Promise<ENUTStatus[]>	Status flags (e.g. ['OL', 'CHRG'])
isOnline()	Promise<boolean>	On mains power
isOnBattery()	Promise<boolean>	On battery power
getBatteryCharge()	Promise<number>	Charge 0-100 or NaN
getBatteryRuntime()	Promise<number>	Runtime in seconds or NaN
getLoad()	Promise<number>	Load 0-100 or NaN
getInputVoltage()	Promise<number>	Input voltage or NaN
getOutputVoltage()	Promise<number>	Output voltage or NaN
getModel()	Promise<string>	UPS model name
getManufacturer()	Promise<string>	UPS manufacturer
getSerial()	Promise<string>	UPS serial number

Session Methods

Method	Returns	Description
login()	Promise<string>	Login to this UPS (for upsmon use)
master()	Promise<string>	Claim master status
getMaster()	Promise<boolean>	Check if master

Passthrough Methods

All NUTClient variable, command, and session methods are available on UPS objects (the UPS name is applied automatically):

await ups.getVariable('battery.charge');
await ups.setVariable('ups.delay.start', '60');
await ups.runCommand('shutdown.return', '60');
await ups.listVariables();
await ups.listCommands();
await ups.listWriteableVariables();
await ups.login();
await ups.master();
await ups.getMaster();

---

RawNUTClient

Low-level TCP client for raw NUT protocol access. Use NUTClient instead unless you need direct protocol control.

import { RawNUTClient } from 'nut-client';

const raw = new RawNUTClient('127.0.0.1', 3493);
const response = await raw.send(['LIST', 'UPS']);

---

Monitor

See Monitor for the dedicated documentation.

---

ENUTStatus

Enum of NUT status codes:

Value	Meaning
OL	On Line
OB	On Battery
LB	Low Battery
HB	High Battery
RB	Replace Battery
FSD	Forced Shutdown
CAL	Calibration
OFF	Off/Asleep
BYPASS	Bypass mode
CHRG	Charging
DISCHRG	Discharging
TRIM	Trimming voltage
BOOST	Boosting voltage
OVER	Overloaded

---

Tracking Types

interface TrackingOptions {
  followTracking?: boolean;         // auto-poll until completion
  trackingTimeout?: number;         // max wait (ms), default: 30000
  trackingPollInterval?: number;    // poll interval (ms), default: 1000
}

type CommandResult =
  | { tracked: true; trackingUid: string }
  | { tracked: false; success: true };

type TrackedResult =
  | { tracked: true; status: 'SUCCESS' | 'ERR' }
  | { tracked: false; success: true };

---

Errors

All errors extend NUTProtocolError. Key error classes:

Error	NUT Code	Description
AccessDeniedError	ACCESS-DENIED	Authentication required
UnknownUPSError	UNKNOWN-UPS	UPS not found
DataStaleError	DATA-STALE	UPS data is stale
DriverNotConnectedError	DRIVER-NOT-CONNECTED	Driver not running
VarNotSupportedError	VAR-NOT-SUPPORTED	Variable not supported
CmdNotSupportedError	CMD-NOT-SUPPORTED	Command not supported
InvalidValueError	INVALID-VALUE	Invalid variable value
SetFailedError	SET-FAILED	Failed to set variable
ReadonlyError	READONLY	Variable is read-only
ConnectionLostError	—	TCP connection lost

See the full list in src/Errors/.