Introduction

cli-aware detects whether an HTTP request comes from a CLI tool (curl, wget, httpie, …), a browser, or something else, allowing you to consistently serve different content based on the environment.

Installation

npm

npm install cli-aware

pnpm

pnpm add cli-aware

yarn

yarn add cli-aware

bun

bun add cli-aware

Quick start

import CliAware from 'cli-aware';

// Works with any Request-like object
const aware = new CliAware(request);

if (aware.cli) {
  // The request comes from curl, wget, httpie, etc.
  console.log(`CLI client: ${aware.client}`); // e.g. "curl"
}

if (aware.browser) {
  // The request comes from Chrome, Firefox, Safari, etc.
}

if (aware.unknown) {
  // Neither a known CLI client nor a recognized browser
}

Framework examples

SvelteKit

+server.ts

import CliAware from 'cli-aware';
import type { RequestHandler } from './$types';

export const GET: RequestHandler = ({ request }) => {
  const aware = new CliAware(request);

  if (aware.cli) {
    return new Response(`Hello, ${aware.client} user!`);
  }

  return new Response('Hello, browser user!');
};

Express

server.ts

import express from 'express';
import CliAware from 'cli-aware';

const app = express();

app.get('/', (req, res) => {
  const aware = new CliAware(req);

  if (aware.cli) {
    res.type('text/plain').send(`Hello, ${aware.client}!`);
  } else {
    res.type('text/html').send('<h1>Hello, browser!</h1>');
  }
});

Next.js

route.ts

import CliAware from 'cli-aware';

export function GET(request: Request) {
  const aware = new CliAware(request);

  if (aware.cli) {
    return new Response(`Hello, ${aware.client} user!`);
  }

  return new Response('<h1>Hello, browser user!</h1>', {
    headers: { 'content-type': 'text/html' },
  });
}

Fetch API / Workers

worker.ts

import CliAware from 'cli-aware';

export default {
  async fetch(request: Request): Promise<Response> {
    const aware = new CliAware(request);

    if (aware.cli) {
      return new Response(`CLI client: ${aware.client}`);
    }

    return new Response('<h1>Browser</h1>', {
      headers: { 'content-type': 'text/html' },
    });
  },
};

Bun

server.ts

import CliAware from 'cli-aware';

export default {
  fetch(request: Request) {
    const aware = new CliAware(request);

    if (aware.cli) {
      return new Response(`Hello from ${aware.client}!`);
    }

    return new Response('Hello from the browser!');
  },
};

The isCliRequest shorthand

If you only need a boolean check:

import { isCliRequest } from 'cli-aware';

if (isCliRequest(request)) {
  // handle CLI
}

Instance properties

Property	Type	Description
request	R (the input you passed)	The original request object
options	O (the options you passed)	The options object (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 a known CLI tool nor a browser
client	string | null	The matched client token (e.g. "curl") when cli is true, otherwise null

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

Supported request shapes

CliAware accepts any object matching Request | { headers?: RequestHeaders }:

• Fetch API Request — from Deno, Bun, Cloudflare Workers, SvelteKit, etc.
• Node.js IncomingMessage — from Express, Koa, Fastify, etc. (plain { headers: Record<string, string> })
• Any object with a headers property — Headers instance or plain object

Header lookup is always case-insensitive.

Contributing

Pull requests are welcome! Before opening a PR, please run:

npm run check && npm run format