Overview

The shorten CLI lets you create short links, view analytics, and manage your links without leaving the terminal. It wraps the Shorten REST API in a fast, scriptable interface.

Installation

npm install -g @shorten-dev/cli

We currently only distribute via npm. If you'd like support for other package managers (Homebrew, pnpm, yarn, etc.), let us know.

Authentication

Log in with the CLI

The easiest way to authenticate is to use the built-in login command:

shorten login

This opens your browser to the API Keys page, prompts you to paste your key, validates it, and saves it to ~/.shorten.json.

Verify the connection

shorten whoami
# => Key: sk_...a1b2
# => Rate limit: 247/300 remaining

Alternative: environment variable

Set your API key as an environment variable:

export SHORTEN_API_KEY="sk_your_key_here"

For persistent auth, add this to your shell profile (~/.bashrc, ~/.zshrc, etc.).

You can also pass the key inline with --key:

shorten --key sk_your_key_here https://docs.example.com

Generate an API key from the API Keys dashboard if you don't have one yet.

Quick start

# Shorten a URL
shorten https://docs.example.com/very-long-url
# => ✓ r.shorten.dev/x7kQ2m (copied to clipboard)

# Use a custom slug
shorten https://docs.example.com/guides --slug my-docs
# => ✓ r.shorten.dev/my-docs (copied to clipboard)

# List your recent links
shorten list

# View analytics for a link
shorten stats x7kQ2m

Shell integration

The CLI copies shortened URLs to your clipboard automatically. You can also pipe output:

# Pipe a URL in
echo "https://docs.example.com/long" | shorten

# Get just the short URL (no formatting)
shorten --quiet https://docs.example.com/long

# Use in a script
SHORT=$(shorten --quiet https://docs.example.com)
echo "Share this link: $SHORT"

Configuration

Config file

The CLI reads from ~/.shorten.json if present:

{
  "api_key": "sk_your_key_here",
  "api_url": "https://shorten.dev/api/v1",
  "default_format": "short",
  "copy_to_clipboard": true
}

Field	Type	Default	Description
`api_key`	string	—	Your API key (overridden by `SHORTEN_API_KEY` env var)
`api_url`	string	`"https://shorten.dev/api/v1"`	API base URL (overridden by `SHORTEN_API_URL` env var)
`default_format`	string	`"pretty"`	Output format: `"pretty"`, `"short"`, or `"json"`
`copy_to_clipboard`	boolean	`true`	Auto-copy shortened URLs to clipboard

Managing config

Use shorten config to manage settings without editing the file directly:

# View all settings
shorten config list

# Set a value
shorten config set api_url http://localhost:3000/api/v1

# Get a value
shorten config get api_url

# Reset all settings
shorten config reset

# Print config file path
shorten config path

Custom API URL

If you're running a local development server or self-hosted instance, configure the API URL:

# Via environment variable
export SHORTEN_API_URL="http://localhost:3000/api/v1"

# Via flag (per-command)
shorten --api-url http://localhost:3000/api/v1 whoami

# Via config file
shorten config set api_url http://localhost:3000/api/v1

Priority: --api-url flag > SHORTEN_API_URL env var > config file > default.

Next steps

CLI Commands Reference

Full list of commands, flags, and options.

API Reference

Understand the underlying REST API.

The shorten CLI lets you create short links, view analytics, and manage your links without leaving the terminal. It wraps the Shorten REST API in a fast, scriptable interface.

Installation

npm install -g @shorten-dev/cli

We currently only distribute via npm. If you'd like support for other package managers (Homebrew, pnpm, yarn, etc.), let us know.

Authentication

Log in with the CLI

The easiest way to authenticate is to use the built-in login command:

shorten login

This opens your browser to the API Keys page, prompts you to paste your key, validates it, and saves it to ~/.shorten.json.

Verify the connection

shorten whoami
# => Key: sk_...a1b2
# => Rate limit: 247/300 remaining

Alternative: environment variable

Set your API key as an environment variable:

export SHORTEN_API_KEY="sk_your_key_here"

For persistent auth, add this to your shell profile (~/.bashrc, ~/.zshrc, etc.).

You can also pass the key inline with --key:

shorten --key sk_your_key_here https://docs.example.com

Generate an API key from the API Keys dashboard if you don't have one yet.

Quick start

# Shorten a URL
shorten https://docs.example.com/very-long-url
# => ✓ r.shorten.dev/x7kQ2m (copied to clipboard)

# Use a custom slug
shorten https://docs.example.com/guides --slug my-docs
# => ✓ r.shorten.dev/my-docs (copied to clipboard)

# List your recent links
shorten list

# View analytics for a link
shorten stats x7kQ2m

Shell integration

The CLI copies shortened URLs to your clipboard automatically. You can also pipe output:

# Pipe a URL in
echo "https://docs.example.com/long" | shorten

# Get just the short URL (no formatting)
shorten --quiet https://docs.example.com/long

# Use in a script
SHORT=$(shorten --quiet https://docs.example.com)
echo "Share this link: $SHORT"

Configuration

Config file

The CLI reads from ~/.shorten.json if present:

{
  "api_key": "sk_your_key_here",
  "api_url": "https://shorten.dev/api/v1",
  "default_format": "short",
  "copy_to_clipboard": true
}

Field	Type	Default	Description
`api_key`	string	—	Your API key (overridden by `SHORTEN_API_KEY` env var)
`api_url`	string	`"https://shorten.dev/api/v1"`	API base URL (overridden by `SHORTEN_API_URL` env var)
`default_format`	string	`"pretty"`	Output format: `"pretty"`, `"short"`, or `"json"`
`copy_to_clipboard`	boolean	`true`	Auto-copy shortened URLs to clipboard

Managing config

Use shorten config to manage settings without editing the file directly:

# View all settings
shorten config list

# Set a value
shorten config set api_url http://localhost:3000/api/v1

# Get a value
shorten config get api_url

# Reset all settings
shorten config reset

# Print config file path
shorten config path

Custom API URL

If you're running a local development server or self-hosted instance, configure the API URL:

# Via environment variable
export SHORTEN_API_URL="http://localhost:3000/api/v1"

# Via flag (per-command)
shorten --api-url http://localhost:3000/api/v1 whoami

# Via config file
shorten config set api_url http://localhost:3000/api/v1

Priority: --api-url flag > SHORTEN_API_URL env var > config file > default.

Overview

Installation

Authentication

Log in with the CLI

Verify the connection

Alternative: environment variable

Quick start

Shell integration

Configuration

Config file

Managing config

Custom API URL

Next steps

CLI Commands Reference

API Reference

On this page

Overview

Installation

Authentication

Log in with the CLI

Verify the connection

Alternative: environment variable

Quick start

Shell integration

Configuration

Config file

Managing config

Custom API URL

Next steps

CLI Commands Reference

API Reference

On this page