CLI Tool

Create and manage branded short links from your terminal. The Xpolink CLI wraps the REST API and works on all plans.

Installation

Install the CLI globally via npm:

npm install -g @xpolink/cli

Verify the installation:

xpolink --version

Authentication

Log in with your API key. You can generate one from your dashboard under Settings → API Keys.

xpolink login xpo_your_api_key_here

Your key is stored locally in ~/.xpolink/config.json. To use a different API base URL (e.g. for self-hosted), pass --base-url:

xpolink login xpo_your_key --base-url https://your-instance.com

Check credentials

xpolink whoami

Log out

xpolink logout

Link Commands

Create a link

xpolink link create https://example.com/my-long-url

# With a custom slug:
xpolink link create https://example.com/my-long-url --slug promo

# With a specific domain:
xpolink link create https://example.com/my-long-url --domain go.yourbrand.com

# With a title:
xpolink link create https://example.com/my-long-url --title "Spring Campaign"

# With per-country geo routes (Business plan):
xpolink link create https://example.com/global \
  --geo US=https://example.com/us \
  --geo GB=https://example.com/uk \
  --geo AU=https://example.com/au

List links

xpolink link list

# With pagination:
xpolink link list --page 2

# Search:
xpolink link list --search "campaign"

Get link details

xpolink link get abc123

Update a link

# Change destination URL (Pro+ plans):
xpolink link update abc123 --url https://new-destination.com

# Update title:
xpolink link update abc123 --title "New Title"

# Deactivate:
xpolink link update abc123 --active false

# Change redirect type:
xpolink link update abc123 --redirect 302

# Toggle geo routing on or off:
xpolink link update abc123 --geo-routing true

Manage geo routes (Business)

# List current geo routes:
xpolink link geo list abc123

# Replace all routes (also enables geo routing):
xpolink link geo set abc123 \
  --route US=https://example.com/us \
  --route GB=https://example.com/uk

# Disable geo routing without deleting routes:
xpolink link geo set abc123 --disable

# Clear all routes and disable:
xpolink link geo clear abc123

Country codes are ISO-3166-1 alpha-2 (e.g. US, GB, AU). Visitors from a matched country are redirected to that target URL; everyone else falls through to the default destination. Business plan only.

View link stats

xpolink link stats abc123

Shows total clicks, top countries, and other analytics based on your plan.

Export click analytics (Business)

# Export to default clicks.csv:
xpolink link export abc123

# Export to a specific file:
xpolink link export abc123 --output campaign-clicks.csv

Downloads raw click events as CSV. Columns: clicked_at, country, city, region, referrer, device_type, browser, os, utm_source, utm_medium, utm_campaign. Business plan only.

List captured emails (Business)

xpolink link emails abc123

# With pagination:
xpolink link emails abc123 --page 2

Shows emails collected via the email gate feature with location and timestamp. Business plan only.

Export captured emails (Business)

# Export to default emails.csv:
xpolink link emails-export abc123

# Export to a specific file:
xpolink link emails-export abc123 --output leads.csv

Delete a link

xpolink link delete abc123

Domain Commands

List domains

xpolink domain list

Lists all domains with their verification status and ID. Unverified domains also show the DNS records you need to configure.

Add a domain

xpolink domain add go.yourbrand.com

After adding, the CLI shows the exact DNS records to configure at your registrar (CNAME or A record, plus an optional TXT verification record). It also shows the domain ID and the verify command to run next.

Get domain details

xpolink domain get DOMAIN_ID

Shows full domain info including DNS records. Useful if you need to re-check the DNS configuration after the initial add.

Verify a domain

xpolink domain verify DOMAIN_ID

Checks if DNS is correctly configured. If verification fails, the CLI re-displays the expected DNS records so you can compare. DNS changes can take up to 48 hours to propagate.

Delete a domain

xpolink domain delete DOMAIN_ID

API Key Commands

List API keys

xpolink api-key list

Any team member can list keys (names and prefixes only — raw keys are never shown after creation).

Create an API key

xpolink api-key create "CI/CD"

The full key is shown once on creation — save it immediately. You won't be able to see it again. Owner only — team members without the owner role will receive a 403 error.

Delete an API key

xpolink api-key delete KEY_ID

Owner only — only team owners can revoke API keys.

Bulk Import

Import links from a JSON file (up to 500 per import, Pro and Business plans):

xpolink import links.json

The JSON file should contain an array of objects. Each object supports these fields: url (required), short_code, domain, title. Example:

[
  { "url": "https://example.com/page-1", "short_code": "promo1" },
  { "url": "https://example.com/page-2", "title": "Campaign 2" }
]

See the API docs for all supported field name aliases.

Configuration

The CLI stores configuration in ~/.xpolink/config.json:

{
  "apiKey": "xpo_your_key",
  "baseUrl": "https://xpolink.app"
}

You can edit this file directly or use xpolink login to update it.

Plan Limits

The CLI respects your plan's limits. The API enforces all restrictions server-side and returns clear error messages:

  • Monthly link creation quota (Free: 50, Pro: 1,000, Business: 3,000)
  • Domain limits (Free: 1, Pro: 5, Business: unlimited)
  • URL editing requires Pro or Business
  • Bulk import requires Pro or Business
  • Click export, captured emails, and email export require Business

For the full API reference, see the API documentation. Questions? Contact us.