Dub

Dub CLI (dub)

The dub CLI is a tool for interacting with the Dub.co link shortening and attribution platform. It lets you shorten URLs, manage links, configure custom domains, and authenticate with your Dub workspace — all from the terminal.

Package name: dub-cli (npm), binary name: dub Source repo: dubinc/dub (monorepo, package at packages/cli)

Installation

npm i -g dub-cli@latest
yarn global add dub-cli@latest
pnpm i -g dub-cli@latest

Global Options

Option	Alias	Description
--version	-v	Display version number
--help	-h	Display help for command

Commands

dub login

Authenticate the CLI with your Dub.co account via OAuth2. Opens a browser window for authentication.

dub login

How it works:

• Opens a local callback server on http://localhost:4587/callback
• Uses the @badgateway/oauth2-client library
• Requests scopes: links.read, links.write, domains.read
• Stores tokens (access, refresh, expiry) in Configstore (typically ~/.config/configstore/dub-cli.json)

Scopes requested:

• links.read — read links in workspace
• links.write — create/update/delete links
• domains.read — read workspace domains

Token refresh happens automatically when config is read and the token has expired.

dub config

View your configured credentials and workspace configuration as colorized JSON.

dub config

Config store: Uses Configstore with the key dub-cli. The stored config includes:

• access_token — OAuth2 access token
• refresh_token — OAuth2 refresh token
• expires_at — token expiry timestamp (ms)
• domain — selected workspace domain

Config file location: ~/.config/configstore/dub-cli.json

dub domains

Configure your workspace domain for link shortening. Presents an interactive prompt listing all available domains from your Dub workspace.

dub domains

Behind the scenes:

• Fetches domain slugs via the Dub SDK (dub.domains.list())
• Lets you select one from an interactive prompt
• Saves the selected domain slug to config via setConfig({ domain: slug })

dub shorten

Create a short link. If called without arguments, enters interactive prompt mode.

dub shorten [url] [key]

Arguments:

Argument	Description
url	Destination URL to shorten
key	Short key/slug for the link (default: auto-generated nanoid)

If no URL provided (interactive mode):

1. Prompts "Enter your Destination URL:"
2. Prompts "Enter your Short link:" (prefilled with auto-generated nanoid)

Uses the Dub SDK's dub.links.create() with the configured domain.

dub links

Search for links in your Dub workspace and display results in a table.

dub links [options]

Options:

Option	Alias	Description	Default
--search [search]	-s	Search term to filter links	—
--limit [limit]	-l	Number of links to fetch	10

Output columns: Short Link, Destination URL, Clicks, Created At

Uses the Dub SDK's dub.links.list() with search and pageSize params.

dub help

Display help for the CLI or a specific command.

dub help [command]

Environment Variables

Variable	Description	Default
DUB_API_URL	Base API URL	https://api.dub.co
DUB_OAUTH_URL	OAuth URL	https://app.dub.co

Architecture

• CLI framework: commander (v11)
• OAuth2 client: @badgateway/oauth2-client
• SDK: dub (Dub.co TypeScript SDK, wraps the Dub REST API)
• Config storage: configstore (JSON file in ~/.config/configstore/dub-cli.json)
• Spinners: ora
• Interactive prompts: prompts
• Browser opening: open
• Output: chalk (colors), json-colorizer (config JSON), console.table (links)

Quick Reference

Task	Command
Install the CLI	npm i -g dub-cli@latest
Check version	dub --version
Authenticate	dub login
View current config	dub config
Select workspace domain	dub domains
Shorten a URL (interactive)	dub shorten
Shorten a URL with custom key	dub shorten <url> <key>
List links (10 most recent)	dub links
Search links by term	dub links -s <term>
List more links	dub links -l 50
Get help	dub help
Get help for a command	dub help shorten

Development

To work on the CLI locally from the dubinc/dub monorepo:

git clone https://github.com/dubinc/dub.git
cd dub/packages/cli
pnpm install
pnpm build
npm link   # makes `dub` available globally

Or run directly without global install:

pnpm start <command>
pnpm start help
pnpm start links

Key Files in Monorepo

File	Purpose
packages/cli/src/index.ts	Entry point, commander setup
packages/cli/src/commands/shorten.ts	dub shorten implementation
packages/cli/src/commands/login.ts	dub login implementation
packages/cli/src/commands/config.ts	dub config implementation
packages/cli/src/commands/domains.ts	dub domains implementation
packages/cli/src/commands/links.ts	dub links implementation
packages/cli/src/utils/config.ts	Config store get/set
packages/cli/src/api/links.ts	SDK wrapper for link creation
packages/cli/src/api/domains.ts	SDK wrapper for domain fetch
packages/cli/src/utils/oauth.ts	OAuth2 client setup
packages/cli/src/utils/handle-error.ts	Error handler utility
packages/cli/src/utils/logger.ts	Logger utility
packages/cli/src/utils/get-nanoid.ts	Nanoid key generator
packages/cli/src/utils/get-package-info.ts	Package version reader
packages/cli/package.json	Dependencies & build config