Every Dub feature, plus offline search, agent-native output, and a local SQLite store no other Dub tool has.
dub-pp-cli covers all 53 Dub API operations as typed commands, then transcends with cross-resource joins the API cannot answer alone — dead-link detection, drift detection, partner leaderboards from /partners/analytics joined with local commissions, bounty submission triage, and a Monday-morning workspace health report. The official dub-cli covers 6 commands; we cover 67.
Learn more at Dub.
Authentication
dub-pp-cli reads DUB_API_KEY from the environment (Speakeasy convention; DUB_TOKEN also accepted for compatibility with prior community CLIs). The key is workspace-scoped — the workspace is implicit in the key. Get one from dub.co/settings/tokens and run dub-pp-cli doctor to verify connectivity.
Quick Start
# Verify API key, base URL, and rate-limit headroom.
dub-pp-cli doctor
# Populate the local SQLite store so search and transcendence commands work offline.
dub-pp-cli sync
# List the workspace's links with the fields agents care about.
dub-pp-cli links list --json --select id,key,url,clicks
# Find dormant links — the headline transcendence feature.
dub-pp-cli links stale --days 90 --json
# Cross-resource Monday-morning report: rate-limit headroom, expiring links, bounty triage backlog.
dub-pp-cli health --json
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
links stale — Find archived, expired, or zero-traffic links across the workspace before they pile up.
Use this to clean up dormant short links before a portfolio review or before bulk-archiving. The /analytics endpoint can't filter links by 'no clicks in N days' in a single call.
dub-pp-cli links stale --days 90 --json --select id,key,clicks,archived
-
links drift — Detect links whose click rate dropped more than threshold percent week-over-week.
Catches dying campaigns before reporting deadlines. Use this in a weekly automation to surface attribution links that quietly stopped converting.
dub-pp-cli links drift --window 7d --threshold 30 --json
-
links duplicates — Find every link in the workspace pointing to the same destination URL.
Surfaces accidental duplicates from bulk-create overruns and consolidation candidates after a migration.
dub-pp-cli links duplicates --json
-
links lint — Audit short-key slugs for lookalike collisions, reserved-word violations, and brand-conflict hazards.
Use this before a brand campaign launch to catch lookalike slugs that confuse partners or get reserved-word treatment.
dub-pp-cli links lint --json
-
links rollup — Performance dashboard aggregated by tag or folder — clicks, leads, sales rolled up across every link wearing each label.
Use this to compare campaign performance across tag dimensions without reconciling 5 separate API calls.
dub-pp-cli links rollup --by clicks --group-by tag --json
-
funnel — Click-to-lead-to-sale conversion rates per link or campaign.
Surfaces where prospects drop off in your attribution funnel. Use before quarterly reporting to spot links with high clicks and low conversion.
dub-pp-cli funnel --link mylink --min-clicks 50 --json
-
customers journey — See every link a customer clicked, when they became a lead, and when they purchased — in one timeline.
Use this for QBR-style account reviews or to debug attribution issues for a specific customer.
dub-pp-cli customers journey cust_abc123 --json
Agent-native plumbing
-
links rewrite — Show every link that would change and the exact patch BEFORE sending.
Use this before any campaign-wide rewrite. Diff preview prevents the worst class of bulk-mutation mistakes.
dub-pp-cli links rewrite --match 'utm_source=oldcampaign' --replace 'utm_source=newcampaign' --dry-run
-
health — Cross-resource Monday-morning report: rate-limit headroom, expired-but-active links, dead destination URLs, unverified domains, dormant tags, bounty submissions awaiting review.
Use this as the first thing every morning, or as a CI canary. Surfaces what needs attention without dashboard hopping.
dub-pp-cli health --json
-
since — What happened in the last N hours? Created, updated, deleted links plus partner approvals, new bounty submissions, and top-clicked entities.
Use this in agent loops to summarize workspace activity since the last check-in. Cheap and idempotent.
dub-pp-cli since 24h --json
Partner ops
-
partners leaderboard — Rank partners by commission earned, conversion rate, and clicks generated.
Use this to identify top performers before a partner-tier review, or dormant partners worth deactivating.
dub-pp-cli partners leaderboard --by commission --top 10 --json
-
partners audit-commissions — Reconcile partners, commissions, bounties, and payouts to flag stale rates, missing payouts, and expired bounties still earning.
Run this before a payout cycle to catch billing surprises. Use in CI before any commission-rate migration.
dub-pp-cli partners audit-commissions --json
-
bounties triage — Group partner-submitted bounty proof by status, age, and bounty type. Surfaces backlog awaiting review.
Run weekly to keep bounty submissions from rotting. Bounty programs lose partner trust when submissions sit unreviewed.
dub-pp-cli bounties triage --status pending --older-than 7d --json
-
bounties payout-projection — Project upcoming payouts from approved-but-unpaid submissions multiplied by current commission rates.
Use this for finance/marketing planning. Surfaces upcoming payout liability before the next payout cycle.
dub-pp-cli bounties payout-projection --window 30d --json
Usage
Run dub-pp-cli --help for the full command reference and flag list.
Commands
bounties
Manage bounties
commissions
Manage commissions
dub-pp-cli commissions bulk-update - Bulk update up to 100 commissions with the same status.dub-pp-cli commissions list - Retrieve a paginated list of commissions for your partner program.dub-pp-cli commissions update - Update an existing commission amount. This is useful for handling refunds (partial or full) or fraudulent sales.
customers
Manage customers
dub-pp-cli customers delete - Delete a customer from a workspace.dub-pp-cli customers get - Retrieve a paginated list of customers for the authenticated workspace.dub-pp-cli customers get-id - Retrieve a customer by ID for the authenticated workspace. To retrieve a customer by external ID, prefix the ID with ext_.dub-pp-cli customers update - Update a customer for the authenticated workspace.
domains
Manage domains
dub-pp-cli domains check-status - Check if a domain name is available for purchase. You can check multiple domains at once.dub-pp-cli domains create - Create a domain for the authenticated workspace.dub-pp-cli domains delete - Delete a domain from a workspace. It cannot be undone. This will also delete all the links associated with the domain.dub-pp-cli domains list - Retrieve a paginated list of domains for the authenticated workspace.dub-pp-cli domains register - Register a domain for the authenticated workspace. Only available for Enterprise Plans.dub-pp-cli domains update - Update a domain for the authenticated workspace.
dub-analytics
Manage dub analytics
dub-pp-cli dub-analytics retrieve-analytics - Retrieve analytics for a link, a domain, or the authenticated workspace. The response type depends on the event and type query parameters.
events
Manage events
dub-pp-cli events list - Retrieve a paginated list of events for the authenticated workspace.
folders
Manage folders
dub-pp-cli folders create - Create a folder for the authenticated workspace.dub-pp-cli folders delete - Delete a folder from the workspace. All existing links will still work, but they will no longer be associated with this folder.dub-pp-cli folders list - Retrieve a paginated list of folders for the authenticated workspace.dub-pp-cli folders update - Update a folder in the workspace.
links
Manage links
dub-pp-cli links bulk-create - Bulk create up to 100 links for the authenticated workspace.dub-pp-cli links bulk-delete - Bulk delete up to 100 links for the authenticated workspace.dub-pp-cli links bulk-update - Bulk update up to 100 links with the same data for the authenticated workspace.dub-pp-cli links create - Create a link for the authenticated workspace.dub-pp-cli links delete - Delete a link for the authenticated workspace.dub-pp-cli links get - Retrieve a paginated list of links for the authenticated workspace.dub-pp-cli links get-count - Retrieve the number of links for the authenticated workspace.dub-pp-cli links get-info - Retrieve the info for a link.dub-pp-cli links update - Update a link for the authenticated workspace. If there's no change, returns it as it is.dub-pp-cli links upsert - Upsert a link for the authenticated workspace by its URL. If a link with the same URL already exists, return it (or update it if there are any changes). Otherwise, a new link will be created.
partners
Manage partners
dub-pp-cli partners approve - Approve a pending partner application to your program. The partner will be enrolled in the specified group and notified of the approval.dub-pp-cli partners ban - Ban a partner from your program. This will disable all links and mark all commissions as canceled.dub-pp-cli partners create - Creates or updates a partner record (upsert behavior). If a partner with the same email already exists, their program enrollment will be updated with the provided tenantId. If no existing partner is found, a new partner will be created using the supplied information.dub-pp-cli partners create-link - Create a link for a partner that is enrolled in your program.dub-pp-cli partners deactivate - This will deactivate the partner from your program and disable all their active links. Their commissions and payouts will remain intact. You can reactivate them later if needed.dub-pp-cli partners list - List all partners for a partner program.dub-pp-cli partners list-applications - Retrieve a paginated list of pending applications for your partner program.dub-pp-cli partners reject - Reject a pending partner application to your program. The partner will be notified via email that their application was not approved.dub-pp-cli partners retrieve-analytics - Retrieve analytics for a partner within a program. The response type vary based on the groupBy query parameter.dub-pp-cli partners retrieve-links - Retrieve a partner's links by their partner ID or tenant ID.dub-pp-cli partners upsert-link - Upsert a link for a partner that is enrolled in your program. If a link with the same URL already exists, return it (or update it if there are any changes). Otherwise, a new link will be created.
payouts
Manage payouts
dub-pp-cli payouts list - Retrieve a paginated list of payouts for your partner program.
qr
Manage qr
dub-pp-cli qr get-qrcode - Retrieve a QR code for a link.
tags
Manage tags
dub-pp-cli tags create - Create a tag for the authenticated workspace.dub-pp-cli tags delete - Delete a tag from the workspace. All existing links will still work, but they will no longer be associated with this tag.dub-pp-cli tags get - Retrieve a paginated list of tags for the authenticated workspace.dub-pp-cli tags update - Update a tag in the workspace.
tokens
Manage tokens
dub-pp-cli tokens create-referrals-embed - Create a referrals embed token for the given partner/tenant. The endpoint first attempts to locate an existing enrollment using the provided tenantId. If no enrollment is found, it resolves the partner by email and creates a new enrollment as needed. This results in an upsert-style flow that guarantees a valid enrollment and returns a usable embed token.
track
Manage track
dub-pp-cli track lead - Track a lead for a short link.dub-pp-cli track open - This endpoint is used to track when a user opens your app via a Dub-powered deep link (for both iOS and Android).dub-pp-cli track sale - Track a sale for a short link.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
dub-pp-cli commissions list
# JSON for scripting and agents
dub-pp-cli commissions list --json
# Filter to specific fields
dub-pp-cli commissions list --json --select id,name,status
# Dry run — show the request without sending
dub-pp-cli commissions list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
dub-pp-cli commissions list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Retryable - creates return "already exists" on retry, deletes return "already deleted"
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
dub-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/dub-pp-cli/config.toml
Environment variables:
Troubleshooting
Authentication errors (exit code 4)
- Run
dub-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $DUB_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized: Invalid API key — Confirm DUB_API_KEY is set and starts with
dub_. Tokens from dub.co/settings/tokens are workspace-scoped.
- 429 rate_limit_exceeded on /analytics — Analytics has tighter per-second caps (Pro 2/s, Advanced 8/s). The client retries with backoff; pass
--page-size 50 to reduce throughput.
- search returns nothing after fresh install — Run
dub-pp-cli sync once to populate the local store. Search queries the local FTS index, not the live API.
- links rewrite blasted too many links — Always use
--dry-run first. The diff preview shows every link that would change before any mutation.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press