pihole-js

A framework-agnostic fully typed JavaScript client for the Pi-hole API.

📚 Docs • 🚀 Getting Started • 📖 API Reference • 📝 Changelog

📦 Installation

npm install pihole-js
pnpm add pihole-js
yarn add pihole-js
bun add pihole-js

🚀 Usage

import PiHoleClient from 'pihole-js';

const client = new PiHoleClient({
  baseUrl: 'http://pi.hole',
  password: 'your-api-password',
  userAgent: 'my-app/1.0',
});

const summary = await client.stats.getSummary();
const blocking = await client.dns.getStatus();

console.log(summary);
console.log(blocking);

📖 API

new PiHoleClient(options)

const client = new PiHoleClient({
  baseUrl: 'http://pi.hole',
  password: 'secret',
  timeoutMs: 10_000,
  userAgent: 'my-app/1.0',
});

Options

interface PiHoleClientOptions {
  baseUrl: string;
  password?: string;
  timeoutMs?: number;
  userAgent?: string;
  fetch?: typeof globalThis.fetch;
  sessionStore?: SessionStore;
}

Selected Methods

Auth:

• client.auth.check()
• client.auth.login(credentials?)
• client.auth.logout()
• client.auth.getSessions()

Stats:

• client.stats.getSummary()
• client.stats.getTopDomains(options?)
• client.stats.getDatabaseTopDomains(options)
• client.stats.getTopClients(options?)
• client.stats.getRecentBlocked(count?)
• client.stats.getDatabaseSummary(options)

History:

• client.history.get()
• client.history.getClients(options?)
• client.history.getDatabase(options)
• client.history.getDatabaseClients(options)

Queries:

• client.queries.list(options?)
• client.queries.getSuggestions()

DNS:

• client.dns.getStatus()
• client.dns.setBlocking(blocking, timer?)
• client.dns.enable()
• client.dns.disable(seconds?)

Domains:

• client.domains.list()
• client.domains.create(type, kind, payload)
• client.domains.update(type, kind, domain, payload)
• client.domains.delete(type, kind, domain)
• client.domains.allow(domain, comment?)
• client.domains.unallow(domain)
• client.domains.deny(domain, comment?)
• client.domains.undeny(domain)
• client.domains.allowRegex(pattern, comment?)
• client.domains.unallowRegex(pattern)
• client.domains.denyRegex(pattern, comment?)
• client.domains.undenyRegex(pattern)
• client.domains.search(domain, options?)

Groups:

• client.groups.list()
• client.groups.get(name)
• client.groups.create(payload)
• client.groups.update(name, payload)
• client.groups.delete(name)

Clients:

• client.clients.list()
• client.clients.get(client)
• client.clients.create(payload)
• client.clients.update(client, payload)
• client.clients.delete(client)
• client.clients.getSuggestions()

Lists:

• client.lists.list(options?)
• client.lists.get(address, options?)
• client.lists.create(type, payload)
• client.lists.update(address, payload)
• client.lists.delete(address, type)

Config:

• client.config.get(options?)
• client.config.patch(config, options?)
• client.config.getSection(element, options?)
• client.config.addArrayItem(element, value, options?)
• client.config.removeArrayItem(element, value, options?)

Network:

• client.network.getDevices(options?)
• client.network.deleteDevice(deviceId)
• client.network.getGateway(options?)
• client.network.getRoutes(options?)
• client.network.getInterfaces(options?)

Info:

• client.info.getSystem()
• client.info.getVersion()
• client.info.getMessages()
• client.info.getMessagesCount()
• client.info.deleteMessage(id)

Logs:

• client.logs.getDnsmasq(options?)
• client.logs.getFtl(options?)
• client.logs.getWebserver(options?)

Teleporter:

• client.teleporter.export()
• client.teleporter.import(archive, selection?)

Actions:

• client.actions.updateGravity(options?)
• client.actions.restartDns()
• client.actions.flushLogs()
• client.actions.flushArp()
• client.actions.flushNetwork()

DHCP:

• client.dhcp.getLeases()
• client.dhcp.deleteLease(ip)

Docs:

• client.docs.getHtml()

PADD:

• client.padd.getSummary()

🔐 Authentication

If you provide a password, the client will authenticate automatically and reuse the returned Pi-hole session.

const client = new PiHoleClient({
  baseUrl: 'http://pi.hole',
  password: 'secret',
});

await client.stats.getSummary();

For passwordless installs, omit the password:

const client = new PiHoleClient({
  baseUrl: 'http://pi.hole',
});

🗂️ Session Stores

By default, each client instance keeps session data in memory.

import PiHoleClient, { MemorySessionStore } from 'pihole-js';

const sessionStore = new MemorySessionStore();

const client = new PiHoleClient({
  baseUrl: 'http://pi.hole',
  password: 'secret',
  sessionStore,
});

If you want to share sessions across client instances, provide your own store implementation that matches the SessionStore interface.

🌐 Custom Fetch

You can inject your own fetch implementation.

import PiHoleClient from 'pihole-js';
import fetch from 'node-fetch';

const client = new PiHoleClient({
  baseUrl: 'http://pi.hole',
  password: 'secret',
  fetch,
});

⚠️ Error Handling

All request, authentication, timeout, and API errors are thrown as PiHoleError.

import PiHoleClient, { PiHoleError } from 'pihole-js';

const client = new PiHoleClient({
  baseUrl: 'http://pi.hole',
  password: 'secret',
});

try {
  await client.stats.getSummary();
} catch (error) {
  if (error instanceof PiHoleError) {
    console.error(error.status);
    console.error(error.code);
    console.error(error.message);
  }
}

👨‍💻 Development

pnpm build

pnpm test

🤝 Contributing

Contributions are always welcome!

Please ensure you run pnpm lint:fix before opening a pull request.

📜 License

AGPL-3.0