Detection Options

The DetectionOptions interface lets you customize which clients are detected and how matching works.

import CliAware from 'cli-aware'

const aware = new CliAware(request, {
    extendClients: ['my-internal-tool'],
})

clients

clients?: readonly string[]

Replace the entire built-in client list with your own. Only the tokens you provide will be detected as CLI clients.

const aware = new CliAware(request, {
    clients: ['my-tool', 'other-tool'],
})

// Only 'my-tool' and 'other-tool' are detected as CLI.
// curl, wget, etc. are no longer recognized.

extendClients

extendClients?: readonly string[]

Add tokens to the built-in list (or to clients, if you also pass it). The defaults are preserved.

const aware = new CliAware(request, {
    extendClients: ['my-custom-cli'],
})

// 'my-custom-cli' is now detected alongside all 23 built-in clients.

Combining clients and extendClients

When both are provided, extendClients appends to the clients array:

const aware = new CliAware(request, {
    clients: ['curl', 'wget'],
    extendClients: ['my-tool'],
})
// Effective list: ['curl', 'wget', 'my-tool']

clientPattern

clientPattern?: RegExp

Replace the matching logic entirely with your own regex. If the regex has a capture group, group 1 is reported as client. If there is no capture group, the whole match is used.

This option takes priority over clients and extendClients.

const aware = new CliAware(request, {
    clientPattern: /my-special-agent\/(\d+)/i,
})

if (aware.cli) {
    console.log(aware.client) // The captured version number
}