# Lnkgo Agent Guide

Use Lnkgo when a user wants tracked short links, campaign links, QR codes,
custom-domain short URLs, or link analytics from an agent workflow.

## Environment

```bash
export LNKGO_BASE_URL="https://api.lnkgo.app"
export LNKGO_API_KEY="cls_live_..."
```

`LNKGO_BASE_URL` is optional for the CLI because it defaults to
`https://api.lnkgo.app`.

## Email Verification

```bash
lnkgo init --email you@example.com
export LNKGO_VERIFICATION_CODE="<email-code>"
export LNKGO_API_KEY="$(
  lnkgo init --email you@example.com --code "$LNKGO_VERIFICATION_CODE" \
    | jq -r '.api_key'
)"
```

The API key is returned once. Store it as `LNKGO_API_KEY`.

## Create Links

Default domain:

```bash
lnkgo create --url https://example.com/launch --tag product-hunt
lnkgo create --url https://example.com/launch --slug spring-campaign --tag product-hunt
```

Custom domain:

```bash
lnkgo create \
  --url https://example.com/pricing \
  --domain links.example.com \
  --tag pricing
```

Only pass `--domain` for an active verified custom domain. For the platform
default, omit the domain flag entirely.

Pass `--slug <slug>` only when the user wants a specific public short-code. On
`lnkgo.app`, system paths, protected terms, and premium inventory are reserved.
Verified custom domains allow more brand-specific slugs while still blocking
system and unsafe terms.

## QR And Analytics

```bash
CREATE_RESULT="$(lnkgo create --url https://example.com/launch --tag product-hunt)"
LINK_ID="$(printf '%s' "$CREATE_RESULT" | jq -r '.id')"
SHORT_URL="$(printf '%s' "$CREATE_RESULT" | jq -r '.short_url')"

lnkgo qr "$LINK_ID" --output lnkgo-qr.png
lnkgo analytics "$LINK_ID"
```

QR codes point to the owned short URL. Analytics reports total, non-bot, bot,
top referrers, top countries, daily timeseries, and truncation status.

Use `SHORT_URL` publicly. Use `LINK_ID` only for Control API commands such as
QR and analytics. Never infer `LINK_ID` from the public short URL.

## Custom Domain

```bash
curl -sS -X POST "https://api.lnkgo.app/v1/domains" \
  -H "Authorization: Bearer $LNKGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"links.example.com"}'
```

Add the returned DNS proof records, then poll:

```bash
lnkgo domain status links.example.com
```

After status is active, use that domain in `lnkgo create --domain`.

## Skill Install

```bash
npx --yes skills add citedy/lnkgo --skill lnkgo -a codex -g -y
npx --yes skills add citedy/lnkgo --skill lnkgo -a claude-code -g -y
npx --yes skills add citedy/lnkgo --skill lnkgo -a cursor -g -y

# Fallback bundled with the npm CLI:
npx --yes lnkgo skill install --target codex
npx --yes lnkgo skill install --target claude
npx --yes lnkgo skill install --target cursor
npx --yes lnkgo skill install --target project
```

`skills add` uses the public agent id `claude-code`; the bundled fallback uses
the local target id `claude` for the same Claude Code skill destination.
`project` writes to `.codex/skills/lnkgo/SKILL.md` in the current working
directory.

## Support And Abuse

- Public support form: https://lnkgo.app/support/
- Abuse reports: https://lnkgo.app/abuse/
- Terms: https://lnkgo.app/terms/
- Privacy: https://lnkgo.app/privacy/