@ctrl/nzbget
    Preparing search index...

    @ctrl/nzbget

    NZBGet

    TypeScript api wrapper for NZBGet using JSON-RPC

    Includes the normalized usenet API shared through @ctrl/shared-usenet and also available in @ctrl/sabnzbd:

    Use the normalized methods by default. Drop to the native NZBGet methods only when you need JSON-RPC specific behavior such as raw config access, raw editQueue commands, or direct append usage.

    npm install @ctrl/nzbget

    Requires Node.js 24 or newer.

    import { Nzbget } from '@ctrl/nzbget';

    const client = new Nzbget({
      baseUrl: 'http://localhost:6789/',
      username: 'nzbget',
      password: 'tegbzn6789',
    });

    async function main() {
      const data = await client.getAllData();
      console.log(data.queue);
    }

    import { Nzbget, UsenetNotFoundError, UsenetPriority } from '@ctrl/nzbget';

    const client = new Nzbget({
      baseUrl: 'http://localhost:6789/',
      username: 'nzbget',
      password: 'tegbzn6789',
    });

    async function main() {
      const id = await client.addNzbUrl('https://example.test/release.nzb', {
        category: 'movies',
        priority: UsenetPriority.high,
        startPaused: false,
      });

      try {
        const job = await client.getQueueJob(id);
        console.log(job.state, job.progress);
      } catch (error) {
        if (error instanceof UsenetNotFoundError) {
          console.log('job missing', error.id);
        }
      }
    }

    Docs: https://nzbget.ep.workers.dev
    NZBGet API Docs: https://nzbget.com/documentation/api/

    getAllData()

    Returns queue, history, categories, scripts, and status in normalized form. This is the broadest normalized read and fits best when you want an overview in one call.

    getQueue()

    Returns normalized active queue items.

    getHistory()

    Returns normalized history items.

    getQueueJob(id)

    Returns one normalized active queue item. Missing ids throw UsenetNotFoundError.

    getHistoryJob(id)

    Returns one normalized history item. Missing ids throw UsenetNotFoundError.

    findJob(id)

    Searches queue first, then history, and returns { source, job } or null. It is the convenient path when you do not know which side the id should be on.

    addNzbFile(...) / addNzbUrl(...)

    Add an NZB and return the normalized queue id as a string. These are the lighter add helpers when an id is enough. The normalized add option names are category, priority, postProcess, postProcessScript, name, password, and startPaused.

    normalizedAddNzb(...)

    Add an NZB from either a URL or file content and return the created normalized queue item. This is the higher-level add helper when you want the normalized job back immediately. If NZBGet sends the job straight to history (e.g. a duplicate marked DELETED/COPY), the history item is returned instead.

    removeJob(id, removeData?)

    Deletes a queue job (GroupDelete / GroupFinalDelete) or, if the id is in history, a history item (HistoryDelete / HistoryFinalDelete).

    stateMessage uses the shared UsenetStateMessage vocabulary: Grabbing, Queued, Downloading, Paused, Post-processing, Completed, Failed, Warning, Deleted, and Unknown.

    NZBGet-specific methods are still available when you need the raw JSON-RPC surface.

    Connection and discovery:

    Queue and rate control:

    System:

    const state = client.exportState();
    const restored = Nzbget.createFromState(config, state);

    Start a disposable NZBGet container on localhost:6789 with the same credentials used by the client defaults:

    docker run -d --name nzbget-local-test \
      -p 6789:6789 \
      -e NZBGET_USER=nzbget \
      -e NZBGET_PASS=tegbzn6789 \
      lscr.io/linuxserver/nzbget:latest

    Run the full local test suite against that container:

    TEST_NZBGET_URL=http://127.0.0.1:6789 TEST_NZBGET_USERNAME=nzbget TEST_NZBGET_PASSWORD=tegbzn6789 pnpm test

    If you only want the container-backed integration spec:

    TEST_NZBGET_URL=http://127.0.0.1:6789 TEST_NZBGET_USERNAME=nzbget TEST_NZBGET_PASSWORD=tegbzn6789 pnpm test test/integration.spec.ts

    Remove the disposable container when you are done:

    docker rm -f nzbget-local-test

    Settings
    Member Visibility

    On This Page
    NZBGet