Skip to main content
Learn how to install and set up the Dub CLI for managing short links from your terminal.

​
Prerequisites

  • Node.js 18 or higher
  • npm, pnpm, or yarn package manager
  • A Dub account (sign up here)

​
Global Installation

Install the CLI globally to use it from anywhere: 
npm install -g dub-cli

​
Verify Installation

Check that the CLI is installed correctly: 
dub --version
You should see the version number (e.g., 0.0.13).

​
Initial Setup

After installation, authenticate with your Dub account:
1

Login

Run the login command:
dub login
This will:
  • Open your default browser
  • Redirect to Dub’s authentication page
  • Start a local server on port 4587
  • Store credentials securely after authentication
2

Configure Domain

Select your workspace domain:
dub domains
Use arrow keys to select from your available domains.
3

Verify Configuration

Check your stored credentials:
dub config
This displays your:
  • Access token
  • Configured domain
  • Token expiration

​
Local Development Setup

For contributing to the CLI or testing unreleased features:
1

Clone Repository

Clone the Dub monorepo:
git clone https://github.com/dubinc/dub.git
cd dub/packages/cli
2

Install Dependencies

Install the required dependencies:
pnpm install
3

Build in Watch Mode

Start the development build:
pnpm dev
This watches for changes and rebuilds automatically.
4

Run Commands

In a separate terminal, run CLI commands:
pnpm start [command]
For example:
pnpm start login
pnpm start shorten https://example.com

​
Production-like Testing

Test the CLI as it would work after installation:
1

Uninstall Existing CLI

If you have the CLI installed globally, remove it first:
npm uninstall -g dub-cli
2

Build Package

Build the CLI from source:
cd packages/cli
pnpm build
3

Link Globally

Link the package to use it globally:
npm link
4

Verify

Test the installation:
dub --version
dub help

​
Configuration Storage

The CLI stores configuration using configstore:
  • macOS: ~/Library/Preferences/dub-cli-nodejs/
  • Linux: ~/.config/dub-cli-nodejs/
  • Windows: %APPDATA%\dub-cli-nodejs\Config\
Configuration includes:
  • Access token
  • Refresh token
  • Selected domain
  • Token expiration time

​
Troubleshooting

​
Port Already in Use

If port 4587 is already in use during login:
  1. Kill the process using the port: 
    # macOS/Linux
lsof -ti:4587 | xargs kill -9

# Windows
netstat -ano | findstr :4587
taskkill /PID <PID> /F
  2. Try logging in again: 
    dub login

​
Command Not Found

If dub command is not found after installation:
  1. Check npm global bin directory: 
    npm config get prefix
  2. Add it to your PATH: 
    # Add to ~/.bashrc, ~/.zshrc, etc.
export PATH="$(npm config get prefix)/bin:$PATH"
  3. Restart your terminal

​
Permission Errors

On macOS/Linux, you may need sudo for global installation: 
sudo npm install -g dub-cli
Alternatively, configure npm to use a different directory: 
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

​
Authentication Issues

If authentication fails:
  1. Clear stored credentials: 
    rm -rf ~/Library/Preferences/dub-cli-nodejs/  # macOS
rm -rf ~/.config/dub-cli-nodejs/              # Linux
  2. Try logging in again: 
    dub login

​
Updating

Update to the latest version: 
npm update -g dub-cli
Check the current version: 
dub --version

​
Uninstalling

Remove the CLI: 
npm uninstall -g dub-cli
Remove configuration files: 
# macOS
rm -rf ~/Library/Preferences/dub-cli-nodejs/

# Linux
rm -rf ~/.config/dub-cli-nodejs/

# Windows
del /f /s /q %APPDATA%\dub-cli-nodejs

​
Next Steps

CLI Commands

Learn all available commands

CLI Overview

Back to CLI overview

API Reference

Explore the API

Server SDKs

Use programmatic SDKs

Build docs developers (and LLMs) love

Get started for freeTalk to us