---
title: "URL shortener docs: CLI, API, MCP, and domains · Flared"
description: "Install the Flared CLI, connect an AI assistant through the MCP server, call the REST API, and add a custom domain for your short links."
---

Documentation

# A short guide to shorter links.

The dashboard, CLI, API, and MCP server share one account. Links, domains, limits, and the plan belong to a workspace, and you can own several. The owner invites members by email under Settings, Members: Free has room for 2 people and Plus for 10, the owner included. Members create and edit links and see analytics; only the owner manages domains, billing, members, webhooks, Slack, Microsoft Teams, analytics forwarding, and automation templates. The owner can make a member the owner, who accepts under Settings, Members. For the CLI and the API, create an API token in the dashboard under Connections, API tokens; it works in the workspace where you created it, and a member’s token cannot add or remove domains. AI assistants sign in with your Flared account instead.

## Install the CLI

Create, list, and measure links from your terminal.

## [Connect an AI agent](https://flared.page/docs/assistants)

Connect Claude, ChatGPT, or Grok to your Flared account.

## Call the API

Create links from your own app with one request.

## Add a custom domain

Put your short links on a domain your audience knows.

## [Plans and limits](https://flared.page/pricing)

Compare Free and Plus. Understand monthly allowances.

## [Self-host](https://flared.page/site/self-host)

Run the open-source core in your own Cloudflare account.

## CLI

Install the CLI, sign in with your API token, and create a link.

```
npm install -g @flaredlink/cli
flared login
flared link create https://example.com/launch --slug launch
```

`flared login` asks for your token without showing it and saves it for your user only. In CI, set `FLARED_TOKEN` instead. A link argument is its ID or its slug. `flared whoami` shows the workspace the token works in, your role there, and the token’s scopes.

```
flared link list --search launch
flared link update launch --destination https://example.com/v2
flared link disable launch
flared link qr launch --format png --out launch.png
flared link create https://example.com/launch --domain go.example.com
flared domain add go.example.com
flared analytics launch --from 2026-09-01
flared usage
```

Add `--json` to any command for machine-readable output. Exit codes are stable, so scripts and CI jobs can rely on them: 0 success, 2 wrong usage, 3 not signed in, 4 not allowed, 5 not found, 6 rejected input, 7 plan limit, 8 rate limited, 9 service unavailable, and 1 for anything else. For a complete workflow, see [short links in GitHub Actions](https://flared.page/blog/short-links-in-github-actions).

For a self-hosted instance, set `FLARED_API_URL` to its API, such as `https://links.example.com/v1`. To deploy one, follow [Self-host on Cloudflare](https://flared.page/site/self-host) and [generate its setup secret](https://flared.page/secrets).

## MCP server

Add `https://api.flared.page/mcp` to your AI assistant as a custom connector. The assistant opens Flared in your browser: sign in, check what it asks for, and approve. You need no API token.

- **Claude:** Settings, Connectors, Add custom connector. Enter the URL.
- **ChatGPT:** turn on developer mode under Settings, Apps, Advanced settings. Then create a connector with the URL and OAuth.
- **Grok:** New Connector, Custom. Enter the URL.
- **Claude Code:** run `claude mcp add --transport http flared https://api.flared.page/mcp`, then `/mcp` to sign in.

The consent page shows the app, where it returns, and what it may do: see links, create and edit links, see analytics, and see usage. With more than one workspace, you choose the ones the assistant can use, and it works only there. When you ask for something without naming a workspace, the assistant asks you which one. Remove it at any time under Connections in a workspace; it stops working there at once.

[Connect an AI assistant](https://flared.page/docs/assistants) has every step, the tools, and example prompts.

The tools are `list_links`, `get_link`, `get_link_analytics`, `get_usage`, `list_workspaces`, `create_link`, `import_links`, `update_link`, `disable_link`, `enable_link`, `list_domains`, `export_links`, `get_link_qr`, `list_automations`, `apply_automation`, `remove_automation`, `list_pages`, `get_page`, `create_page`, and `update_page`. Ask your assistant to create a link on your domain, show its QR code, summarize last week’s clicks, or add a button to your link page.

## API

Send requests to `https://api.flared.page/v1` with your token as a bearer token. An `Idempotency-Key` header makes a retried create safe. Each token works only for the scopes you chose when you created it.

```
curl https://api.flared.page/v1/links \
  -H "Authorization: Bearer $FLARED_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-001" \
  -d '{"destination":"https://example.com/launch","slug":"launch"}'
```

To import links in bulk, send `POST /v1/links/import` with the `links:write` scope, an `Idempotency-Key` header, and a body of `dryRun` and up to 25 `items`. Each item gets its own result. Send `dryRun: true` first: it checks every item and creates nothing.

The [OpenAPI description](https://api.flared.page/v1/openapi.json) lists every route, its scope, and its responses.

## Webhooks

A webhook sends a signed HTTPS request to your endpoint when a link is created, changed, turned off, or turned on, or when it reaches a click count. The workspace owner adds endpoints under Settings, Webhooks. Plus and Founding Lifetime include 5 endpoints per workspace. [Webhooks](https://flared.page/docs/webhooks) has the events, the payloads, and how to verify a signature.

## Slack

Flared posts link alerts, a weekly summary, and automation runs in public Slack channels. The workspace owner connects one Slack workspace under Integrations, Slack, then adds rules: each rule picks a channel and its events, such as a link created or a click milestone, or the day and hour of a weekly summary. Plus and Founding Lifetime include 20 Slack rules per workspace. [Slack](https://flared.page/docs/slack) has the permissions, the messages, and how to disconnect.

## Microsoft Teams

Flared posts link alerts, a weekly summary, and automation runs in Microsoft Teams channels. For each channel, the workspace owner makes a workflow from the Teams template “Send webhook alerts to a channel” and pastes its link under Integrations, Microsoft Teams. Each rule picks its events or the day and hour of a weekly summary. Plus and Founding Lifetime include 20 Teams rules per workspace. [Microsoft Teams](https://flared.page/docs/teams) has the setup steps, the messages, and what to do when a link stops working.

## Zapier

The Flared app for Zapier starts a Zap when a link is created, changed, or turned off, or when it reaches a click count. Zap steps create, change, turn off, turn on, and find links. Anyone in the workspace connects it from Integrations and signs in with their Flared account. The actions and the search work on every plan; the triggers need Plus or Founding Lifetime. [Zapier](https://flared.page/docs/zapier) has the triggers, the fields, the limits, and how to disconnect.

## Browser extension

The Flared browser extension shortens the page you are on, or any link on it, from the Chrome toolbar or the right-click menu. It copies the short URL and its QR code. It signs in with your Flared account and works on every plan. [Browser extension](https://flared.page/docs/browser-extension) has the install steps, the permissions, and how to sign out.

## Analytics forwarding

Flared sends each counted click to Google Analytics 4, Amplitude, Mixpanel, or PostHog as the event `flared_click`, with the short URL, the UTM tags, the country, the device, and a visitor ID. The workspace owner connects each tool under Integrations with its key. Plus and Founding Lifetime include it. [Analytics forwarding](https://flared.page/docs/analytics-forwarding) has the keys, the fields, the visitor cookie, and the retries.

## Automations

An automation changes a link’s destination, turns the link off, sends a webhook, posts in Slack or Teams, or emails the workspace owner on an end date, a number of days after the link was created, a click count, or when the destination stops loading. Use it for link expiry, scheduled changes, and broken-page fallbacks. The workspace owner creates templates on the Automations page, and anyone in the workspace applies them to links from the Links page, with `POST /v1/automations/{id}/links`, or through MCP. Plus and Founding Lifetime keep 25 templates per workspace. [Automations](https://flared.page/docs/automations) has the triggers, the destination checks, the actions, the timing, and the API.

## Link pages

A link page shows your name, a short bio, and buttons that open your short links, at `name.flared.site`. Make one under Pages in the dashboard, with `/v1/pages`, or through MCP. Free includes 1 page with a “Made with Flared” badge. Plus and Founding Lifetime include 10 pages without the badge, payment cards, embeds, and a page at the root of your own domain. Button clicks count as link clicks; page views do not use your click allowance. [Link pages](https://flared.page/docs/pages) has the blocks, the themes, the addresses, the analytics, and the API.

## Custom domains

In the dashboard, open Domains and add a subdomain such as `go.example.com`. At your DNS provider, add one record:

```
go.example.com  CNAME  customers.flared.link
```

If your DNS is on Cloudflare, set the record’s proxy status to DNS only, so your own zone’s rules do not change the redirect.

Flared checks the record and issues the HTTPS certificate for you; this usually takes a few minutes and at most about an hour. Then pick the domain when you create a link. Root domains such as `example.com` are not supported. Free includes 5 custom domains; Plus includes 10. Removing a domain stops its links; adding it again brings them back.

From the CLI, run `flared domain add go.example.com`, then `flared domain check go.example.com`. Through the API, use `POST /v1/domains` with the `domains:write` scope.

## QR codes

Every link has a QR code of its short URL. Download it as SVG or PNG from the link’s page in the dashboard, with `flared link qr`, or from `GET /v1/links/{id}/qr?format=png`. The address of a link never changes, so a printed code keeps working as long as the link is on. See [how to change a QR code after printing](https://flared.page/blog/change-qr-code-after-printing).

## UTM parameters

In the dashboard, open More options under the destination, or edit a link, and fill in Source, Medium, Campaign, Term, or Content. Flared adds them to the destination as `utm_source`, `utm_medium`, and so on; clear a field to remove it. From the CLI, use `--utm-source`, `--utm-medium`, `--utm-campaign`, `--utm-term`, and `--utm-content` on `flared link create` or `flared link update`. Through MCP, pass a `utm` object to `create_link` or `update_link`. The API takes the parameters as part of `destination`. See [UTM parameters on short links](https://flared.page/blog/utm-parameters-short-links) to test them.

## App links for iPhone and Android

A link can send iPhone and Android visitors to a different destination, such as your app. Everyone else, and link previews in chat apps, go to the destination. Use a universal link or app link (https), or an app scheme such as `myapp://item/42`; Android also takes `intent://` links. If the app is not installed, an https link opens in the browser, while an app scheme can show an error, so prefer https links where your app supports them.

Set them under More options in the dashboard, with `--ios` and `--android` in the CLI (`--clear-ios` and `--clear-android` remove them), as `iosDestination` and `androidDestination` in the API (`null` removes one), or through MCP. Analytics count every click on the link, whichever destination it went to.

## Passwords and start and end times

On Plus, a link can open at a start time, stop at an end time, and send visitors to another address after the end. Before the start, visitors see that the link is not open yet; after the end without an address, they see that it has ended. A link can also ask for a password: visitors enter it before they go to the destination, and the click counts then. Flared stores only a hash of the password and never shows it again. Each visitor gets 10 tries a minute.

Set them under More options in the dashboard, with `--starts-at`, `--ends-at`, `--ended-destination`, and `--password` in the CLI (`--clear-*` removes one), as `startsAt`, `endsAt`, `endedDestination`, and `password` in the API (`null` removes one; reads show `hasPassword`), or through MCP. Times are ISO 8601 with `Z` or an offset. A password protects the short link only: anyone who knows the destination can still open it. After a change to Free, the values stay and you can remove them.

## Link cards

A link card is what Slack, LinkedIn, X, WhatsApp, and other apps show when someone shares a link. Without a card of its own, a short link shows the destination page's title, description, and image. On Plus, you can set a card title, a card description, and a card image (PNG, JPEG, or WebP, up to 5 MB; 1200 × 630 pixels looks best). The apps that build cards get the card; people still go to the destination. A link with a password shows its card too, and the card never names the destination.

Set them under More options in the dashboard, with `--preview-title`, `--preview-description`, and `--preview-image` in the CLI (`--clear-*` removes one), as `previewTitle` and `previewDescription` in the API (`null` removes one) with `PUT /v1/links/{id}/preview-image` for the image, or through MCP (title and description). Apps keep a card for a while after they first fetch it, so a change can take time to show in a chat that already has the link. After a change to Free, the card stays and you can remove it.

## Usage and limits

Each workspace has limits for active links, custom domains, and clicks recorded each calendar month (UTC). At 80% and 100% of a limit, the dashboard shows a warning and Flared emails the workspace owner once. The email names the workspace.

When the monthly clicks are full, your links keep redirecting, but new clicks are not recorded until the next month. Flared counts the clicks it did not record, so you can see the gap. At the link or domain limit, existing links and domains keep working; only new ones are blocked.

See your usage with `flared usage`, the `get_usage` tool, or `GET /v1/usage` with the `usage:read` scope. Each names the workspace it reports on.

## Export your data

Download every link and your retained click history as one JSON file from Settings, General in the dashboard, or only the links as CSV. From the terminal, run `flared export --out flared.json` with a token that has the `links:read` and `analytics:read` scopes.

Scripts can read the same data from `GET /v1/export/links`, `GET /v1/export/daily-totals`, and `GET /v1/export/daily-dimensions`. Each returns a page and a `nextCursor`; follow it until it is null. Flared keeps no copy of the file.

## Plans and billing

Each workspace has its own plan. Its owner changes the plan under Settings, Plan and billing in the dashboard, which shows the current plan, the usage, and the next renewal. You can own one workspace on Free; each other workspace you own needs Plus or Founding Lifetime before it can hold active links. Choose Plus monthly, Plus annual, or Founding Lifetime while seats remain. Polar runs the checkout, and Plus starts when Polar confirms the payment.

A switch between monthly and annual billing applies at the next renewal, and you can keep your current interval until then. Manage billing opens the Polar portal, where you cancel, update your card, and download invoices. A canceled plan keeps Plus until the paid period ends.

When Plus or Lifetime ends, that workspace returns to the Free limits. Your links and domains keep working. Analytics older than 30 days stay readable for 30 more days, and Plan and billing shows the date.

The [terms of service](https://flared.page/terms) and the [refund policy](https://flared.page/refunds) apply to every plan. To report a short link that leads to phishing, malware, or spam, or to ask for a review of a block, use the [report form](https://flared.page/report).

Read the full source and contributor guide on [GitHub](https://github.com/FlaredLink/Flared).
