API Reference

CliAware (default export)

Accepts a request object and optional detection option.

import CliAware from 'cli-aware'

const aware = new CliAware(request)
const aware = new CliAware(request, options)

Constructor

new CliAware<R extends RequestInput, O extends DetectionOptions>(
    request: R,
    options?: O
): CliAware<R, O>

Throws TypeError if request is null or undefined.

Instance properties

All properties are readonly.

Property	Type	Description
request	R	The request object passed to the constructor
options	O	The options object passed to the constructor (defaults to {})
cli	boolean	true if the request comes from a known CLI client
browser	boolean	true if the request comes from a recognized browser
unknown	boolean	true if the client is neither CLI nor browser
client	string | null	The matched client token (e.g. "curl") when cli is true; null otherwise

Exactly one of cli, browser, or unknown is always true.

---

isCliRequest()

A convenience function that returns true if the request comes from a known CLI client.

import { isCliRequest } from 'cli-aware'

function isCliRequest(
    request: RequestInput,
    options?: DetectionOptions
): boolean

Equivalent to new CliAware(request, options).cli.

---

detectClient()

A lower-level pure function that takes a User-Agent string (and optionally headers and options) and returns a detection result.

import { detectClient } from 'cli-aware'

function detectClient(
    userAgent?: string | null,
    headers?: RequestHeaders | null,
    options?: DetectionOptions
): DetectionResult

If userAgent is empty/null and headers is provided, it reads the user-agent header from headers as a fallback.

User-Agent strings longer than 2048 characters are truncated before matching (ReDoS protection).

Example

import { detectClient } from 'cli-aware'

detectClient('curl/8.4.0')
// => { type: 'cli', client: 'curl' }

detectClient('Mozilla/5.0 ... Chrome/120.0 Safari/537.36')
// => { type: 'browser', client: null }

detectClient(null)
// => { type: 'unknown', client: null }

---

DEFAULT_CLI_CLIENTS

A frozen readonly string[] containing the 23 built-in CLI client tokens:

import { DEFAULT_CLI_CLIENTS } from 'cli-aware'

Token	Examples
curl	curl/8.4.0
libcurl	libcurl/8.4.0
wget	Wget/1.21.4
httpie	HTTPie/3.2.2
python-requests	python-requests/2.31.0
python-urllib	Python-urllib/3.11
aiohttp	aiohttp/3.8.5
python-httpx	python-httpx/0.25.0
httpx	HTTPX/0.25.0
go-http-client	Go-http-client/2.0
okhttp	okhttp/4.12.0
node-fetch	node-fetch/3.3.2
axios	axios/1.6.2
undici	undici
bun	Bun/1.0.14
deno	Deno/1.38.2
postmanruntime	PostmanRuntime/7.35.0
insomnia	insomnia/2023.5.8
powershell	PowerShell/7.4.0
windowspowershell	WindowsPowerShell/5.1
reqwest	reqwest/0.11.24
java	Java/17.0.9
lwp-request	lwp-request
libwww-perl	libwww-perl

This array is Object.freeze-d and cannot be mutated.

---

Types

RequestInput

type RequestInput = Request | { headers?: RequestHeaders }

RequestHeaders

type RequestHeaders = Headers | Record<string, string | string[] | undefined>

DetectionResult

interface DetectionResult {
    type: DetectionType
    client: string | null
}

DetectionType

type DetectionType = 'cli' | 'browser' | 'unknown'

DetectionOptions

interface DetectionOptions {
    clients?: readonly string[]
    extendClients?: readonly string[]
    clientPattern?: RegExp
}

See Detection Options for details.