How to install and use the Linkbreakers CLI

Short answer

The Linkbreakers CLI gives you a fast command-line interface for common workspace operations like listing links, creating short URLs, managing directories, and checking custom domains. The easiest way to install it on macOS or Linux is:

After installation, authenticate with a workspace token using linkbreakers auth set-token --token YOUR_TOKEN, then start using commands like linkbreakers links list or linkbreakers links create.

Quick summary

• The CLI binary is named linkbreakers
• It is designed for humans, scripts, and AI agents
• macOS and Linux can install with a one-line shell command
• Windows can install from the GitHub Releases zip asset
• The CLI can notify you when a newer version is available
• Updates can be applied with linkbreakers self-update

What the CLI is useful for

The Linkbreakers CLI is useful when you want to work with Linkbreakers outside the dashboard, automate repetitive tasks, or integrate workspace operations into shell scripts, CI jobs, internal tooling, or AI-driven workflows.

Common use cases include:

• creating and managing shortened links
• listing and organizing links inside directories
• checking custom domain status from a terminal
• calling the API directly with linkbreakers raw
• giving LLMs a stable command surface they can execute reliably

Prerequisites

Before using the CLI, you need:

1. A Linkbreakers account and workspace
2. A workspace API token
3. A supported platform:
   • macOS
   • Linux
   • Windows

Step 1: Install the CLI

macOS and Linux

Use the installer:

curl -fsSL https://cli.linkbreakers.com/install.sh | bash

The installer:

• detects your OS and architecture automatically
• fetches the latest released version
• installs the linkbreakers binary into a standard executable path

Windows

Download the latest .zip archive from the GitHub Releases page:

https://github.com/linkbreakers-com/linkbreakers-cli/releases

Then extract linkbreakers.exe and place it somewhere in your PATH.

Step 2: Create a workspace token

1. Log in to app.linkbreakers.com
2. Go to Dashboard → API Tokens
3. Create a new token
4. Copy it immediately

For CLI and backend usage, use a token that has the permissions required for the operations you plan to run.

Step 3: Authenticate the CLI

The easiest approach is to persist your token locally:

linkbreakers auth set-token --token YOUR_WORKSPACE_TOKEN

You can verify the resolved configuration with:

linkbreakers auth status

You can also use environment variables instead of saving config:

export LINKBREAKERS_TOKEN=YOUR_WORKSPACE_TOKEN
export LINKBREAKERS_BASE_URL=https://api.linkbreakers.com

Step 4: Run your first commands

List links

linkbreakers links list --page-size 20

Create a link

linkbreakers links create \
  --destination https://example.com \
  --name "Spring campaign" \
  --tags marketing,spring

Get a single link

linkbreakers links get LINK_ID

List directories

linkbreakers directories list --recursive

Check custom domains

linkbreakers custom-domains list

Call the API directly

If a dedicated subcommand does not exist yet, use the raw mode:

linkbreakers raw GET /v1/links?pageSize=5

Output formats

By default, the CLI returns JSON, which makes it easy to pipe into tools and LLM workflows.

You can also request table output for supported list commands:

linkbreakers links list --output table

Updating the CLI

The CLI periodically checks whether a newer version is available and will show a message when an update exists.

To update directly from the terminal:

linkbreakers self-update

You can also rerun the installer:

curl -fsSL https://cli.linkbreakers.com/install.sh | bash

Windows update note

Windows users should currently update by downloading the latest release artifact manually from GitHub Releases.

Help and documentation

The CLI includes built-in help:

linkbreakers help
linkbreakers links help
linkbreakers custom-domains help

This makes it useful not only for developers, but also for AI assistants that need a predictable command structure with explicit flags and examples.

Troubleshooting

command not found: linkbreakers

The binary is installed, but the install directory is not in your shell PATH. Add the install directory to PATH, then restart your shell.

missing API token

Set a token first:

linkbreakers auth set-token --token YOUR_WORKSPACE_TOKEN

Or use LINKBREAKERS_TOKEN.

self-update failed

This usually means:

• the binary location is not writable
• the current platform is not supported by in-place update
• the release asset could not be downloaded

In those cases, rerun the installer or download the latest release manually.

Related guides

• How to use the Linkbreakers API
• Linkbreakers TypeScript SDK: Complete Integration Guide
• Linkbreakers Python SDK Quick Start
• How to set up and configure the Linkbreakers MCP server