npm package: @fynlink/cli
Description: Official command-line interface for Fynlink
Latest version: 0.1.0-beta.0

# @fynlink/cli

Official command-line interface for Fynlink, powered by [`@fynlink/sdk`](https://www.npmjs.com/package/@fynlink/sdk).

Website: https://fyn.link

## Requirements

- Node.js `>= 20.10.0`

## Install

```bash
npm i -g @fynlink/cli
```

The package exposes two equivalent commands:

```bash
fyn --help
fynlink --help
```

## Quick Start

1. Add a profile (interactive):

```bash
fyn profile add
```

2. Add a profile (non-interactive):

```bash
fyn profile add \
  --name dev \
  --token "$FYN_TOKEN" \
  --secret "$FYN_SECRET" \
  --base-url "https://api.fynlink.com/v1" \
  --set-active
```

3. Verify active profile:

```bash
fyn profile current
```

4. Call APIs:

```bash
fyn links list --limit 10
```

## Global Options

These options work on every command:

```text
--profile <name>
--token <value>
--secret <value>
--base-url <url>
--timeout-ms <number>
--debug
--output <json|table|yaml>
--json
--no-color
```

Environment variables are also supported:

```text
FYN_PROFILE
FYN_TOKEN
FYN_SECRET
FYN_BASE_URL
FYN_TIMEOUT_MS
FYN_DEBUG
FYN_COLOR
```

Resolution precedence is: CLI flags -> environment -> selected profile.

## Profiles

```bash
# Add profile with prompts for missing values
fyn profile add

# Add profile fully from flags
fyn profile add --name staging --token "<token>" --secret "<secret>" --set-active

# List all profiles
fyn profile list

# Show active profile
fyn profile current

# Switch active profile
fyn profile use staging

# Show one profile
fyn profile show staging

# Remove profile (skip confirmation)
fyn profile remove staging --yes
```

`profile add` validates the token by calling bootstrap info and stores team metadata (team id/name, token name) on success.

## Info

```bash
# Get bootstrap info
fyn info get

# Force refresh (bypass SDK bootstrap cache)
fyn info get --force
```

## Teams

```bash
# Get current team
fyn teams get

# Update team (interactive if --name is omitted)
fyn teams update --name "Growth Team"
```

## Members

```bash
# List members
fyn members list

# Include owner
fyn members list --include-owner

# Get a member
fyn members get member_123

# Invite (interactive if flags omitted)
fyn members invite --email dev@example.com --role admin

# Update role (interactive if --role omitted)
fyn members update member_123 --role editor

# Remove member (skip confirmation)
fyn members remove member_123 --yes
```

## Domains

```bash
# List domains
fyn domains list --page 1 --limit 20

# Get domain by id
fyn domains get domain_123

# Create domain (interactive if --domain omitted)
fyn domains create \
  --domain links.example.com \
  --description "Primary branded domain" \
  --not-found-url "https://www.example.com/404" \
  --root-redirect "https://www.example.com" \
  --gpc

# Verify DNS/status
fyn domains verify domain_123

# Update domain fields
fyn domains update domain_123 --description "Updated description" --gpc true

# Remove domain (skip confirmation)
fyn domains remove domain_123 --yes
```

## Links

```bash
# Create link (interactive if --target omitted)
fyn links create \
  --target "https://www.example.com/pricing" \
  --domain links.example.com \
  --slug spring-sale \
  --title "Spring Campaign" \
  --notes "Created from CLI" \
  --tag campaign spring \
  --ios-target "https://apps.apple.com/app/id123" \
  --android-target "https://play.google.com/store/apps/details?id=com.example.app" \
  --geo US=https://us.example.com/pricing CA=https://ca.example.com/pricing \
  --safe-mode true \
  --analytics full \
  --expiry-seconds 86400

# Get one link
fyn links get link_123

# List links with filters
fyn links list \
  --page 1 \
  --limit 20 \
  --sort-by created_at \
  --sort-order desc \
  --filter-domain links.example.com \
  --filter-tracking full \
  --filter-safe-mode true \
  --filter-private false \
  --filter-password false

# Update link
fyn links update link_123 --title "Updated title" --tag campaign q2 --private false

# Clear password and expiry
fyn links update link_123 --password null --expiry-seconds null

# Delete link (skip confirmation)
fyn links delete link_123 --yes
```

Notes:

- Link `status` and `viaApi` are response fields from backend/system state.
- They are not accepted as create/update input flags.

## Analytics

```bash
# Total clicks
fyn analytics clicks link_123

# Timeseries with date range
fyn analytics timeseries link_123 \
  --start 2026-03-01T00:00:00Z \
  --end 2026-03-31T23:59:59Z \
  --granularity day

# Browser split with filters
fyn analytics browsers link_123 \
  --country US IN \
  --browser Chrome Safari

# Other breakdowns
fyn analytics devices link_123
fyn analytics countries link_123
fyn analytics referrers link_123 --referrer google.com x.com
```

## Output Modes

```bash
# Human-readable default output
fyn links get link_123

# JSON for scripting
fyn links list --json

# YAML output
fyn links list --output yaml

# Disable ANSI colors
fyn links get link_123 --no-color
```

## Automation Examples

```bash
# Select profile once and reuse
fyn profile use production
fyn links list --limit 100 --json

# Use env vars in CI
FYN_TOKEN="<token>" FYN_SECRET="<secret>" fyn links list --json

# Parse JSON output
fyn links list --json | jq '.data[0].id'
```