Quickstart: API and Dashboard

Purpose and Scope

This quickstart gives a new Dub user the shortest practical path from understanding the product to creating a working short link. Dub describes itself as the open-source link attribution platform for short links, conversion tracking, and affiliate programs, so the first successful task is usually creating a short URL that points to a destination URL and can later participate in attribution and analytics workflows. The same link resource is available through the hosted dashboard, the public API family, and the CLI, which lets teams choose between manual setup, scripted automation, and terminal-driven workflows.

Sources: README.md, apps/web/lib/openapi/links/index.ts, packages/cli/README.md

A short link in Dub has two user-facing parts: the destination URL and the short key. The destination URL is where visitors are ultimately redirected. The short key is the path segment used on a Dub-managed or workspace domain. In the dashboard, official docs present this as entering a destination URL and optionally choosing a custom short link in the link builder. In the CLI implementation, the same two inputs are represented by the optional url and key arguments to the shorten command, and the command can prompt for them when they are not supplied.

Sources: packages/cli/src/commands/shorten.ts

Relevant Source Files

README.md — Establishes Dub as the open-source link attribution platform and names short links, conversion tracking, and affiliate programs as the core product areas.
apps/web/lib/openapi/links/index.ts — Registers the Links API paths, including create, list, count, retrieve-info, update, delete, bulk, and upsert routes.
packages/cli/README.md — Documents the public dub CLI commands, including login, config, domains, shorten, links, and help.
packages/cli/src/commands/shorten.ts — Implements the dub shorten command, including arguments, prompts, generated keys, API call, spinner state, and error handling.

Core Primitives

The first primitive is the workspace. A workspace is the operating context that owns links, domains, and credentials. The CLI makes this explicit by requiring configuration before a link can be shortened: the shorten command calls getConfig() before collecting or submitting link data. For a dashboard user, the equivalent step is being in the intended workspace before pressing the create-link action. Treat workspace selection as part of link creation, because a link key can only be meaningful in combination with the domain and workspace where it will be resolved.

Sources: packages/cli/src/commands/shorten.ts, packages/cli/README.md

The second primitive is the link itself. In the OpenAPI registry, the main collection path is /links, with post mapped to link creation and get mapped to listing links. That tells API users that creating the first link is not a special onboarding-only action; it is the normal Links API create operation. The same registry also exposes /links/info for retrieving link information, /links/{linkId} for mutation by identifier, /links/count for counts, /links/bulk for batch operations, and /links/upsert for idempotent creation-or-update workflows.

Sources: apps/web/lib/openapi/links/index.ts

The third primitive is the domain. The CLI command list includes dub domains, described as configuring the workspace domain, and the shorten command returns a full shortLink after creation. That separation is important: link creation can be as simple as destination plus key, but the final URL depends on the workspace domain configuration. If a team wants branded links, it should configure domains early; if it only needs a first functional link, it can create one and then revisit domain management as a follow-up.

Sources: packages/cli/README.md, packages/cli/src/commands/shorten.ts

Quickstart Flow

Start in the dashboard when you want the most visual path. In Dub’s link builder, create a link by choosing the create-link action, entering the destination URL, and optionally specifying the custom short link key. This mirrors the same conceptual fields used by the CLI and API: the destination is the URL visitors should reach, and the key controls the memorable short path. Dashboard creation is best for a first manual setup because it also gives immediate access to link options such as password protection, deep-link configuration, and other workspace settings surfaced in the product UI.

Sources: README.md

Use the API when link creation needs to be automated by an application, onboarding workflow, marketing operation, or migration script. The repository’s OpenAPI path registry shows that link creation is a POST operation on /links. A minimal API quickstart should therefore authenticate with a Dub API credential, send the destination URL and optional key to the create-link endpoint, and store the returned short link for display or campaign use. After that, use GET /links to confirm the link is listed or /links/info when a workflow needs information about a particular short URL.

Sources: apps/web/lib/openapi/links/index.ts

# Conceptual API flow
POST /links
GET /links
GET /links/info

Use the CLI when you want a terminal-first workflow or a fast way to create links while developing. The CLI README describes dub login for authentication, dub config for checking configured workspace credentials, dub domains for workspace domain configuration, and dub shorten [url] [key] for creating short links. It also includes dub links [options] for searching links by name and limiting result count, which makes it useful immediately after creation to verify that your new link exists in the workspace.

Sources: packages/cli/README.md

dub login
dub config
dub domains
dub shorten https://example.com/my-destination my-key
dub links --limit 10

CLI Creation Behavior

The dub shorten command is intentionally ergonomic for both scripted and interactive usage. It declares two optional arguments: [url] for the destination URL and [key] for the short key. If a key is not provided, the command definition uses getNanoid() as the default key generator. If the destination URL is not provided, it opens prompts for both the destination and short link key, pre-filling the key prompt with another generated value. This means a user can run a fully specified command, or simply run dub shorten and answer prompts.

Sources: packages/cli/src/commands/shorten.ts

Once input has been collected, the command starts an ora spinner with the message Creating new short link, calls createLink(linkData), and prints the returned generatedShortLink.shortLink in green on success. Failures are handled in two layers: the inner block fails the spinner and rethrows the error, and the outer block delegates to handleError(error). This gives the command a clear happy path for quickstarts while preserving centralized error behavior for authentication, configuration, API, or validation failures.

Sources: packages/cli/src/commands/shorten.ts

# Interactive mode
dub shorten
 
# Positional-argument mode
dub shorten https://dub.co docs-home

API-to-Code Mapping

The Links API registry is the best compact map for understanding where quickstart operations fit into the larger link lifecycle. POST /links is the create operation used by API quickstarts and by the CLI’s underlying createLink helper. GET /links is the list operation used to inspect workspace links. GET /links/count supports count-based reporting, while GET /links/info supports lookup-style reads. Mutation routes are separated by intent: PATCH /links/{linkId} updates one link, DELETE /links/{linkId} deletes one link, PATCH and DELETE under /links/bulk operate on multiple links, and PUT /links/upsert supports create-or-update semantics.

Sources: apps/web/lib/openapi/links/index.ts, packages/cli/src/commands/shorten.ts

For a first integration, keep the workflow narrow: create one link, read it back, and only then add advanced behaviors. Dub’s official docs show that link creation can later be extended with product capabilities such as password-protected links and deep links, but those features should not obscure the core contract. The repository sources show a clean center of gravity: the OpenAPI Links module names the operations, the CLI wraps the create operation for terminal use, and the README frames why links matter as part of attribution.

Sources: README.md, apps/web/lib/openapi/links/index.ts, packages/cli/README.md

Next Steps

After the first link works, choose the next path based on how the link will be used. If marketers will manage links manually, continue in the dashboard and configure branded domains, link settings, and analytics sharing. If developers will generate links from an application, continue into the Links API pages and model your integration around /links, /links/{linkId}, /links/bulk, and /links/upsert. If your team prefers terminal workflows, read the CLI reference and standardize dub login, dub config, dub domains, dub shorten, and dub links as part of your operating runbook.

Sources: apps/web/lib/openapi/links/index.ts, packages/cli/README.md

Ask a question...