---
title: "How to install and use the Linkbreakers CLI"
description: "Complete guide to installing, authenticating, updating, and using the Linkbreakers CLI for link management, directories, custom domains, and raw API access."
canonical: "https://linkbreakers.com/help/article/linkbreakers-cli-setup"
last-updated: 2026-10-11
---

# How to install and use the Linkbreakers CLI

> Complete guide to installing, authenticating, updating, and using the Linkbreakers CLI for link management, directories, custom domains, and raw API access.

## 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:

<div class="my-8 rounded-2xl bg-primary p-5 shadow-sm text-white one-liner-install">
  <p class="text-xs font-semibold uppercase tracking-[0.2em] text-white/80">One-line install</p>
  <p class="mt-2 text-sm text-white/90">Install the latest Linkbreakers CLI without choosing a version manually.</p>
  <div class="mt-3 rounded-xl bg-white px-4 py-3 text-primary">
    <div class="flex items-center gap-3">
      <div class="flex-1 font-mono text-sm overflow-x-auto" data-install-command>curl -fsSL https://cli.linkbreakers.com/install.sh | bash</div>
      <button
        class="shrink-0 inline-flex items-center justify-center rounded-lg bg-primary/10 p-2 text-primary transition hover:bg-primary/20"
        onclick="
          const code = this.closest('.one-liner-install').querySelector('[data-install-command]').textContent.trim();
          navigator.clipboard.writeText(code).then(() => {
            const original = this.innerHTML;
            this.innerHTML = '<svg class=\'w-4 h-4\' fill=\'none\' stroke=\'currentColor\' viewBox=\'0 0 24 24\'><path stroke-linecap=\'round\' stroke-linejoin=\'round\' stroke-width=\'2\' d=\'M5 13l4 4L19 7\'></path></svg>';
            setTimeout(() => { this.innerHTML = original; }, 2000);
          }).catch(() => {});
        "
        title="Copy installer command"
        aria-label="Copy installer command"
      >
        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z"></path>
        </svg>
      </button>
    </div>
  </div>
</div>

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 any LLM a stable command surface to interact with Linkbreakers

### Using the CLI with your favorite LLM

The CLI is designed to work seamlessly with any AI coding assistant — not just Claude. Once installed and authenticated, any LLM that can execute terminal commands (GitHub Copilot, Cursor, Windsurf, or any other AI tool) can run `linkbreakers` commands to create links, pull analytics, manage domains, and automate QR code workflows.

The CLI outputs structured JSON by default, making it trivially parseable by AI agents. Combined with the MCP server for Claude and other MCP-compatible clients, Linkbreakers is the only QR code management platform built from the ground up for AI-driven workflows.

## 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:

```bash
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](https://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:

```bash
linkbreakers auth set-token --token YOUR_WORKSPACE_TOKEN
```

You can verify the resolved configuration with:

```bash
linkbreakers auth status
```

You can also use environment variables instead of saving config:

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

## Step 4: Run your first commands

### List links

```bash
linkbreakers links list --page-size 20
```

### Create a link

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

### Get a single link

```bash
linkbreakers links get LINK_ID
```

### List directories

```bash
linkbreakers directories list --recursive
```

### Check custom domains

```bash
linkbreakers custom-domains list
```

### Call the API directly

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

```bash
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:

```bash
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:

```bash
linkbreakers self-update
```

You can also rerun the installer:

```bash
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:

```bash
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:

```bash
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](https://linkbreakers.com/help/article/how-to-use-the-linkbreakers-api)
- [Linkbreakers TypeScript SDK: Complete Integration Guide](https://linkbreakers.com/help/article/typescript-sdk-quickstart)
- [Linkbreakers Python SDK Quick Start](https://linkbreakers.com/help/article/python-sdk-quickstart)
- [How to set up and configure the Linkbreakers MCP server](https://linkbreakers.com/help/article/mcp-server-setup)
- [How Linkbreakers works with AI agents](/help/article/linkbreakers-for-ai-agents)