---
title: "How to install and use the Linkbreakers CLI"
description: "Install the Linkbreakers CLI, sign up or authenticate in one command, and reach every API operation from the terminal: links, QR codes, workflows, analytics and more."
canonical: "https://linkbreakers.com/help/article/linkbreakers-cli-setup"
last-updated: 2026-10-21
---

# How to install and use the Linkbreakers CLI

> Install the Linkbreakers CLI, sign up or authenticate in one command, and reach every API operation from the terminal: links, QR codes, workflows, analytics and more.

## Short answer

The Linkbreakers CLI puts the whole Linkbreakers API in your terminal: every API operation is a command, generated from the API's OpenAPI document, so links, QR codes, workflows, visitors and analytics are all one command away. 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>

No account yet? `linkbreakers signup --email you@example.com` creates a workspace and saves its token in one command. Already have one? Authenticate with `linkbreakers auth set-token --token YOUR_TOKEN`. Then start with `linkbreakers links create` or `linkbreakers links list`.

## Quick summary

- The CLI binary is named `linkbreakers`
- Every API operation is a command (`linkbreakers <service> <operation>`), generated from the OpenAPI document, so the CLI always matches the API
- `linkbreakers signup --email <email>` creates a workspace and its token in one step, no account needed
- It is designed for humans, scripts, and AI agents, with JSON output
- 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
- building workflows, reading visitors and pulling analytics, since every API operation has a command
- 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.

An agent with no token can start from nothing: `npx -y linkbreakers-cli signup --email <your email>` creates a workspace and saves its token, then the next command creates links. See [From one prompt to a tracked link in seconds](/help/article/from-one-prompt-to-a-tracked-link-in-seconds). The CLI outputs structured JSON, 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 workspace, or none: `linkbreakers signup` creates one
2. 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

### npm (any OS with Node.js 18+)

```bash
npm install -g linkbreakers-cli
```

Or run it without installing anything: `npx -y linkbreakers-cli <command>`. The npm package `linkbreakers` is the TypeScript SDK; the CLI is `linkbreakers-cli`.

### 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: Sign up or authenticate

### No account yet: sign up from the CLI

```bash
linkbreakers signup --email you@example.com
```

This creates a free workspace and saves its API token, so every other command works right away. We email you a link and a 6-digit code to claim the workspace: open it within 24 hours, or the workspace is deleted with everything in it. Until you claim it, each command reminds you of the deadline, and once you do, the saved token gains the claimed workspace's full permissions on its own.

### Existing account: use 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. Then persist it 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 3: 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 --tags spring
```

### Get a single link

```bash
linkbreakers links get --id LINK_ID --include qrcodeSignedUrl
```

### List directories

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

### Check custom domains

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

### Read analytics

```bash
linkbreakers analytics-data get-top-links --limit 10
linkbreakers metrics get-workspace-metric
```

### Everything else

Every API operation is a command: `linkbreakers <service> <operation>`. `linkbreakers --help` lists the services and `--help` on a command lists its flags, read from the request's fields:

- scalar fields are flags: `--destination`, `--qrcode-enabled=false`, `--page-size 20`
- list fields repeat: `--tags spring --tags print`
- structured fields take JSON: `--metadata '{"campaign":"spring"}'`
- `--data` takes the whole request body as JSON, `@file.json`, or `-` for stdin, and flags set fields on top of it

When the API gains an operation, the next CLI release has the command.

## Output

The CLI returns JSON, which makes it easy to pipe into tools and LLM workflows. When a call fails, it prints the API's error code and message, which say what to do next.

## 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 links create --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.

### `no API token configured`

With an account, set a token: `linkbreakers auth set-token --token YOUR_WORKSPACE_TOKEN`, or use `LINKBREAKERS_TOKEN`. Without one, `linkbreakers signup --email you@example.com` creates a workspace and saves its 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)