Linkly CLI

@linkly-link-shortener/cli — a command-line interface for the Linkly link shortener API. Create and manage short links, custom domains, click analytics, and webhooks from your terminal.

Requirements

• Node.js 20 or newer

Installation

Install the CLI globally from npm:

npm install -g @linkly-link-shortener/cli
linkly --help

From source

To build the CLI from this repository — for development, or before it is published to npm:

cd integrations/cli
npm install
npm run build
npm link          # optional — puts `linkly` on your PATH

Without npm link, run it as node dist/index.js <command>.

This document uses linkly for brevity.

Quick start

linkly auth login --api-key                 # paste your API key when prompted
linkly workspaces list
linkly links create --url https://example.com --name "My first link"
linkly links list

Authentication

The CLI supports OAuth and API keys. Credentials are saved to ~/.config/linkly/config.json (file mode 0600) and persist across runs — you only log in once.

Log in with an API key

linkly auth login --api-key                 # prompts for the key
linkly auth login --api-key <key>           # or pass it inline

Find your API key in your Linkly account's API settings.

Log in with OAuth

linkly auth login

Opens your browser for the OAuth 2.0 authorization-code flow. The CLI starts a temporary server on a loopback address (127.0.0.1) to capture the redirect, then exchanges the code for an access token. OAuth access tokens do not expire.

Check status / log out

linkly auth status     # auth method, API URL, workspace, accessible workspaces
linkly auth logout     # revoke (OAuth) and remove stored credentials

Workspaces

Most commands act on a workspace. After login the CLI auto-selects a workspace if your account has exactly one; otherwise pick a default:

linkly workspaces use <id>

Override the default for a single command with --workspace <id>.

Configuration

Environment variables

| Variable | Purpose | | --- | --- | | LINKLY_API_KEY | API key, used when no credentials are stored | | LINKLY_ACCESS_TOKEN | OAuth access token, used when no credentials are stored | | LINKLY_WORKSPACE_ID | default workspace ID | | LINKLY_API_URL | API base URL (default: https://app.linklyhq.com) | | LINKLY_CONFIG_DIR | directory for the config file | | LINKLY_OAUTH_CLIENT_ID / LINKLY_OAUTH_CLIENT_SECRET | override the OAuth client (for non-production servers) | | NO_COLOR | disable colored output |

Precedence: command-line flag → environment variable → config file → default.

Config file

Stored at ~/.config/linkly/config.json, or $XDG_CONFIG_HOME/linkly/config.json, or $LINKLY_CONFIG_DIR/config.json.

linkly config path     # print the config file path
linkly config show     # show current configuration (secrets redacted)

Global options

| Option | Description | | --- | --- | | -V, --version | print the CLI version | | --no-color | disable colored output | | -h, --help | show help for any command |

Common options

Available on every command that talks to the API:

| Option | Description | | --- | --- | | --api-url <url> | Linkly API base URL | | -w, --workspace <id> | workspace ID to operate on | | --api-key <key> | API key, overriding stored credentials | | --json | output raw JSON instead of a formatted table | | -y, --yes | skip confirmation prompts |

Commands

Authentication — linkly auth

linkly auth login

Log in via OAuth (browser) or with an API key.

| Option | Description | | --- | --- | | --api-url <url> | Linkly API base URL | | --api-key [key] | log in with an API key instead of OAuth (prompts if no value) |

linkly auth login
linkly auth login --api-key

linkly auth logout

Revoke and remove stored credentials.

linkly auth logout

linkly auth status

Show authentication status and the workspaces you can access.

linkly auth status

Workspaces — linkly workspaces (alias ws)

linkly workspaces list

List workspaces you can access.

linkly workspaces list

linkly workspaces use <id>

Set the default workspace for subsequent commands.

linkly workspaces use 42

linkly workspaces update [id]

Update a workspace's name or webhook URL. id defaults to the selected workspace.

| Option | Description | | --- | --- | | --name <name> | new workspace name | | --webhooks <url> | workspace-level webhook URL |

linkly workspaces update --name "Marketing"

Links — linkly links (alias link)

linkly links list

List links in the workspace.

| Option | Description | | --- | --- | | -p, --page <n> | page number (default: 1) | | -n, --page-size <n> | results per page (default: 20) | | -s, --search <query> | filter by search term | | --sort-by <field> | sort field (id, name, url, clicks_total, inserted_at, …) | | --sort-dir <dir> | sort direction: asc or desc |

linkly links list --search promo --sort-by clicks_total --sort-dir desc

linkly links get <id>

Show full details for a link, including its short URL.

linkly links get 12345

linkly links create

Create a new short link.

| Option | Description | | --- | --- | | -u, --url <url> | destination URL (required) | | --name <name> | link nickname | | --slug <slug> | custom slug, e.g. /promo | | --domain <domain> | custom domain | | --domain-id <id> | domain ID (alternative to --domain) | | --note <note> | private note | | --disabled | create the link in a disabled state | | --utm-source <value> | utm_source parameter | | --utm-medium <value> | utm_medium parameter | | --utm-campaign <value> | utm_campaign parameter | | --utm-term <value> | utm_term parameter | | --utm-content <value> | utm_content parameter |

linkly links create --url https://example.com --name "Promo" --slug /promo

linkly links update <id>

Update an existing link. Accepts the same field flags as create (--name, --slug, --domain, --domain-id, --note, --utm-*), plus:

| Option | Description | | --- | --- | | -u, --url <url> | destination URL | | --enabled | enable the link | | --disabled | disable the link |

linkly links update 12345 --url https://example.com/new

linkly links delete <ids...>

Delete one or more links. Prompts for confirmation unless -y is given.

linkly links delete 12345 12346

linkly links export

Export all links as JSON or CSV.

| Option | Description | | --- | --- | | -f, --format <format> | json or csv (default: json) | | -s, --search <query> | filter exported links | | -o, --output <file> | write to a file instead of stdout |

linkly links export --format csv --output links.csv

linkly links qr <id>

Download the QR code PNG for a link.

| Option | Description | | --- | --- | | -o, --output <file> | output file path (default: linkly-qr-<id>.png) |

linkly links qr 12345 --output qr.png

linkly links sparklines <ids...>

Show click-history sparkline data for one or more links (JSON output).

linkly links sparklines 12345 12346

Domains — linkly domains (alias domain)

linkly domains list

List custom domains in the workspace.

linkly domains list

linkly domains create <name>

Add a custom domain to the workspace.

linkly domains create links.example.com

linkly domains delete <id>

Delete a custom domain. Prompts for confirmation unless -y is given.

linkly domains delete 678

linkly domains favicon <id>

Set the favicon URL for a domain.

| Option | Description | | --- | --- | | --url <url> | favicon image URL (required) |

linkly domains favicon 678 --url https://example.com/favicon.ico

Analytics — linkly analytics (alias stats)

linkly analytics timeseries

Time-series click counts over a date range (JSON output).

| Option | Description | | --- | --- | | --start <date> | start date, YYYY-MM-DD | | --end <date> | end date, YYYY-MM-DD | | --link <id> | filter by a single link ID | | --link-ids <ids> | filter by comma-separated link IDs | | --unique | count unique clicks only | | --no-bots | exclude bot / robot traffic |

linkly analytics timeseries --start 2026-01-01 --end 2026-01-31

linkly analytics by <dimension>

Click counts grouped by a dimension. Valid dimensions: country, platform, browser, referer, isp, link_id, top_params.

| Option | Description | | --- | --- | | --start <date> | start date, YYYY-MM-DD | | --end <date> | end date, YYYY-MM-DD | | --link <id> | filter by a single link ID | | --unique | count unique clicks only | | --no-bots | exclude bot / robot traffic |

linkly analytics by country --start 2026-01-01

linkly analytics export

Export click records as JSON or CSV.

| Option | Description | | --- | --- | | --start <date> | start date, YYYY-MM-DD | | --end <date> | end date, YYYY-MM-DD | | --link <id> | filter by link ID | | -f, --format <format> | json or csv (default: json) | | -o, --output <file> | write to a file instead of stdout |

linkly analytics export --format csv --output clicks.csv

linkly analytics recent

List recent individual click records.

linkly analytics recent

Webhooks — linkly webhooks (alias hooks)

Each webhook command targets the workspace by default, or a link when --link <id> is supplied.

linkly webhooks list

List webhooks for a link or the workspace.

| Option | Description | | --- | --- | | --link <id> | target a link instead of the workspace |

linkly webhooks list
linkly webhooks list --link 12345

linkly webhooks add <url>

Subscribe a webhook URL to link or workspace events.

| Option | Description | | --- | --- | | --link <id> | target a link instead of the workspace |

linkly webhooks add https://example.com/hook --link 12345

linkly webhooks remove <url>

Unsubscribe a webhook URL. Prompts for confirmation unless -y is given.

| Option | Description | | --- | --- | | --link <id> | target a link instead of the workspace |

linkly webhooks remove https://example.com/hook --link 12345

Configuration — linkly config

linkly config path

Print the path to the CLI config file.

linkly config path

linkly config show

Show the current configuration, with secrets redacted.

linkly config show

Output

By default, list commands render as tables and single records as aligned key/value pairs. Pass --json to any command for the raw API response — useful for scripting:

linkly links list --json | jq '.links[].url'

Color is enabled on interactive terminals; disable it with --no-color or by setting the NO_COLOR environment variable.

For AI agents

Coding assistants with shell access — Claude Code, Cursor, and similar — can use the CLI directly:

• Pass --json to any command for structured output instead of a table.
• Run linkly schema to dump the entire command tree (commands, arguments, options) as JSON for capability discovery.
• linkly --help and linkly <command> --help document everything, with examples.

Assistants that cannot run shell commands should use the Linkly MCP Server instead.

Exit codes

• 0 — success
• 1 — error (authentication failure, API error, invalid input, …)

Resources

• Linkly website
• Sign up / log in