JavaScript SDK & CLI

Official JavaScript client for shorter.sh. Includes a programmatic SDK and a command-line tool. Zero runtime dependencies, works with Node.js ≥18, Bun, and Deno.

Installation

Install globally to use the shorter command anywhere in your terminal:

Global install

npm install -g shorter.sh

Or add it as a project dependency to use the SDK in your application:

Project dependency

npm install shorter.sh

ℹ️

You need an API key to use the SDK or CLI. Create one from your dashboard.

Quick Start

TypeScript

import { ShorterClient } from 'shorter.sh';

const client = new ShorterClient({
  apiKey: 'sk_your_api_key_here',
});

const { shortUrl } = await client.shorten('https://example.com');
console.log(shortUrl); // https://shorter.sh/xK9mP2

Configuration

Option	Type	Description
apiKey	string	Your API key. Falls back to `SHORTER_API_KEY` env var.
baseUrl	string	API base URL. Defaults to `https://shorter.sh`
fetch	function	Custom fetch implementation. Useful for testing.

Shorten URLs

client.shorten(url)

const result = await client.shorten('https://example.com/very/long/url');

console.log(result.shortCode);   // "xK9mP2"
console.log(result.shortUrl);    // "https://shorter.sh/xK9mP2"
console.log(result.originalUrl); // "https://example.com/very/long/url"

List URLs

client.list(options?)

const { urls, pagination, totalClicks } = await client.list({
  page: 1,
  limit: 50,
});

for (const url of urls) {
  console.log(url.shortUrl, url.originalUrl, url.clickCount);
}

Each URL object contains: id, shortCode, shortUrl, originalUrl, clickCount, createdAt.

Delete URLs

client.delete(shortCode)

await client.delete('xK9mP2');
// Deleted URLs return 410 Gone when visited

Analytics

Overview (all URLs)

client.analytics.overview(options?)

const overview = await client.analytics.overview({
  start: '2024-01-01',
  end: '2024-01-31',
});

console.log(overview.totalClicks);
console.log(overview.uniqueVisitors);
console.log(overview.topUrls);          // Top performing URLs
console.log(overview.countryBreakdown); // Clicks by country
console.log(overview.deviceBreakdown);  // Clicks by device type

Per-URL analytics

client.analytics.url(shortCode, options?)

// Basic stats
const stats = await client.analytics.url('xK9mP2');
console.log(stats.summary.totalClicks);

// With dimension breakdown
const byCountry = await client.analytics.url('xK9mP2', {
  dimension: 'country',
});
console.log(byCountry.breakdown);

// Full detail (all breakdowns at once)
const detail = await client.analytics.url('xK9mP2', { detail: true });
console.log(detail.breakdowns); // country, device_type, browser, os, referrer_domain, language

Available dimensions

country device_type browser os referrer_domain language

Error Handling

All errors extend ShorterError with message, status, and code properties.

Error handling

import { ShorterClient, ValidationError, NotFoundError } from 'shorter.sh';

try {
  await client.shorten('not-a-url');
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.message); // "Invalid URL"
    console.log(err.code);    // "INVALID_URL"
    console.log(err.status);  // 400
  }
}

Error Class	Status	When
ValidationError	400	Invalid URL, missing fields, unsafe URL
AuthenticationError	401	Invalid or missing API key
ForbiddenError	403	Account suspended, access denied
NotFoundError	404	URL not found or not owned by you
RateLimitError	429	Too many requests
ServerError	500	Server-side error
NetworkError	0	DNS failure, timeout, no internet

CLI Setup

Install globally

npm install -g shorter.sh

On first use, the CLI will prompt for your API key and save it securely. You can also set it manually:

Configure API key

shorter config set api-key sk_your_api_key_here

Environment variables

Variable	Description
SHORTER_API_KEY	API key (overrides config file)
SHORTER_BASE_URL	Base URL (overrides config file)
NO_COLOR	Disable colored output

Commands

Shorten a URL

shorter https://example.com
# ✓ https://shorter.sh/xK9mP2
#   Copied to clipboard!

shorter https://example.com --no-copy  # skip clipboard

List your URLs

shorter list
shorter list --page 2 --limit 10
shorter ls  # alias

Delete a URL

shorter delete xK9mP2       # prompts for confirmation
shorter delete xK9mP2 --yes # skip confirmation
shorter rm xK9mP2           # alias

View analytics

shorter analytics                              # overview of all URLs
shorter analytics xK9mP2                      # per-URL stats
shorter analytics xK9mP2 --dimension country  # breakdown by country
shorter stats xK9mP2                          # alias

Manage config

shorter config set api-key sk_your_key   # save API key
shorter config set base-url https://...  # custom base URL
shorter config get api-key               # show masked key
shorter config path                      # show config file location

→

View the package on npm or the source on GitHub.