ULink CLI

CLI tool for verifying and managing universal links (iOS) and app links (Android) configuration for ULink projects.

AI-Assisted Setup (Recommended)

If you use Claude Code, Cursor, Codex, or another AI coding agent, the easiest way to use the ULink CLI is to let your AI agent drive it. Install the ULink onboarding skill in one command:

npx skills add https://ulink.ly

Then ask your agent to "setup ulink" — it'll install this CLI for you, run ulink verify against your project, and walk you through any failures. Works with 50+ AI agents via the open agent-skills CLI. Learn more →

Installation

npm (zero-install)

If you have Node.js, run the CLI with no install via @ulinkly/cli:

npx @ulinkly/cli --help
npx @ulinkly/cli verify

Or install it globally:

npm install -g @ulinkly/cli
ulink --version

@ulinkly/cli is a thin launcher that downloads the matching native binary on first run and caches it. The npm version maps 1:1 to a CLI release (e.g. 1.2.0 → v1.2.0).

Quick Install (script)

macOS / Linux:

curl -fsSL https://ulink.ly/install.sh | bash

Windows (PowerShell):

irm https://ulink.ly/install.ps1 | iex

Install Specific Version

macOS / Linux:

curl -fsSL https://ulink.ly/install.sh | bash -s -- --version v1.0.0

Windows:

& ([scriptblock]::Create((irm https://ulink.ly/install.ps1))) -Version v1.0.0

For Dart Developers

dart pub global activate --source git https://github.com/FlywheelStudio/ulink_cli.git

Manual Download

Download binaries directly from GitHub Releases.

Quick Start

# 1. Login to your ULink account
ulink login

# 2. Navigate to your project directory
cd /path/to/your/app

# 3. Link to your ULink project
ulink project set

# 4. Verify your configuration
ulink verify

Commands

`ulink login`

Authenticate with your ULink account. Supports three authentication methods:

# Browser-based login (default, recommended)
ulink login

# Email/password login
ulink login --password

# API key login
ulink login --api-key

`ulink logout`

Clear stored credentials:

ulink logout

`ulink project set`

Link the current directory to a ULink project:

# Interactive project selection
ulink project set

# Set project by slug directly
ulink project set --slug my-project

# Set for a specific path
ulink project set --path ./my-app

`ulink project show`

Show the currently linked project for a directory:

ulink project show

# For a specific path
ulink project show --path ./my-app

`ulink api-keys`

Manage a project's client SDK API keys (the key you pass to UlinkSDK.initialize). Requires a signed-in user — run ulink login first. The project is taken from the saved directory config, or pass --project-id.

# List keys (metadata only; the secret is never shown here)
ulink api-keys list

# Create a key — the full value is printed once and cannot be retrieved again
ulink api-keys create --name "Production"

# Revoke a key by id
ulink api-keys revoke <keyId>

Add --json to list/create for machine-readable output.

`ulink verify`

Verify your project's deep link configuration:

# Verify current directory
ulink verify

# Verify specific path
ulink verify --path ./my-app

# Verbose output
ulink verify -v

# CI: fail if the run wasn't a full verification (dashboard cross-check skipped)
ulink verify --strict

The dashboard cross-checks (comparing local config against your ULink project and fetching the hosted AASA / assetlinks.json) only run when authenticated (ulink login or --api-key). Without them the run is reported as PARTIAL and, by default, still exits 0 so unauthenticated smoke tests don't break. Pass --strict to make a partial run fail instead.

Only skips that mean something was not verified (chiefly the dashboard cross-check) make a run PARTIAL. Optional environment probes that simply couldn't run — no booted simulator, no adb, or a managed-Expo project with no native directories — are reported as optional skips, do not downgrade the verdict, and do not trip --strict.

Exit codes: 0 fully verified (or passed with warnings; optional probes may be skipped), 1 errors, 2 --strict and the run was only a partial verification.

`ulink fix`

Interactive mode to fix configuration issues:

# Fix issues in current directory
ulink fix

# Fix issues in specific path
ulink fix --path ./my-app

`ulink import firebase`

Migrate your Firebase Dynamic Links (FDL) to ULink. Parses an FDL export, recreates each link under your ULink domain, and verifies routing + attribution parity for every link.

# Dry-run preview (default — never calls the API):
ulink import firebase --input fdl-export.json --domain acme.ulink.app

# Read a list of *.page.link URLs from stdin and print the manifest as JSON:
cat links.txt | ulink import firebase -i - -d acme.ulink.app --json

# Create the links for real (needs an API key):
ulink import firebase -i fdl-export.json -d acme.ulink.app --live --api-key $ULINK_API_KEY

Accepted inputs (auto-detected): a DynamicLinkInfo JSON object, an FDL create-request wrapper, a batch { "links": [...] }, a newline-delimited list of FDL long-link URLs, or a CSV with a header row of your link inventory. Use - for --input to read from stdin.

Option	Short	Description
`--input`	`-i`	Path to your FDL export (`-` for stdin). Required.
`--domain`	`-d`	Your ULink domain for the new links. Required.
`--out`	`-o`	Output dir for the manifest + per-link JSON (default `./ulink-import`).
`--live`		Create links via the ULink API (needs `--api-key`/`ULINK_API_KEY`).
`--api-key`		ULink API key for `--live` (or set `ULINK_API_KEY`).
`--dry-run`		Preview only; never calls the API (default until `--live`).
`--no-verify`		Skip routing + attribution parity checks (on by default).
`--json`		Print the manifest as JSON to stdout (for piping).

Every run preserves attribution (UTM + iTunes Connect params, gclid) and per-platform routing intent, forwarding them via the link's passthrough parameters so they reach your app on open.

`ulink resolve`

Show where a ULink short URL resolves on each platform (iOS / iPad / Android / desktop), plus the in-app deep link and any attribution parameters the link forwards. Read-only: it never creates or mutates anything — it just reads back how a live link routes via GET /sdk/resolve.

# Human-readable per-platform resolution:
ulink resolve https://acme.ulink.app/promo-spring

# Machine-readable output (for piping / CI parity checks):
ulink resolve acme.ulink.app/promo-spring --json

Option	Description
`--url`	The ULink short URL (or pass it as the first positional argument).
`--api-key`	ULink API key (or set `ULINK_API_KEY`). Optional — only needed to read a link's forwarded attribution parameters, which are visible to the owning app.
`--json`	Print the machine-readable resolution to stdout.

Exit codes: 0 resolved, 1 not found / unreachable / API error, 2 bad usage.

`ulink version`

Show version information:

ulink version
# or
ulink --version

Global Options

Option	Short	Description
`--verbose`	`-v`	Enable verbose output
`--interactive`	`-i`	Enable interactive mode
`--api-url`		Override API base URL (for development)
`--help`	`-h`	Show help message
`--version`	`-V`	Show version information

What It Verifies

1. SDK Package Installation

Flutter: Checks pubspec.yaml for flutter_ulink_sdk
React Native / Expo: Checks package.json for @ulinkly/react-native (and app.json for the Expo config plugin)
Android: Checks build.gradle for ly.ulink:ulink-sdk
iOS: Checks Podfile or Package.swift for ULinkSDK

2. Local Configuration Files

iOS: Info.plist, entitlements file (Associated Domains, URL Types)
Android: AndroidManifest.xml (intent filters, App Links)
Flutter: Both iOS and Android configurations
React Native / Expo: Both iOS and Android native config when present (bare RN or after expo prebuild); managed Expo projects are verified via the config plugin in app.json

3. ULink Project Configuration

Fetches project configuration from ULink API
Cross-references with local configuration
Validates bundle IDs, package names, and domains

4. Well-Known Files

iOS: Tests AASA (Apple App Site Association) file accessibility and validity
Android: Tests Asset Links JSON file accessibility and validity

5. Runtime Tests (Optional)

iOS: Tests universal link opening in simulator
Android: Checks app links verification status via ADB

Requirements

For iOS testing: Xcode with xcrun simctl
For Android testing: Android SDK with adb in PATH

Examples

# Full workflow for a Flutter project
ulink login
cd ~/projects/my-flutter-app
ulink project set --slug my-app
ulink verify -v

# Verify iOS-only project
cd ~/projects/my-ios-app
ulink project set
ulink verify --path ./ios

# Verify a React Native / Expo project
cd ~/projects/my-rn-app
ulink project set
ulink verify -v   # run after `npx expo prebuild` for full native checks

# Fix configuration issues interactively
ulink fix -v

Troubleshooting

"Not authenticated" error

Run ulink login to authenticate with your ULink account.

"No project linked" error

Run ulink project set to link your directory to a ULink project.

Verification failures

Run ulink verify -v for verbose output to see detailed error messages.

Support

Documentation: https://ulink.ly/docs
Issues: GitHub Issues

Name		Name	Last commit message	Last commit date
.claude/agents		.claude/agents
.github/workflows		.github/workflows
bin		bin
docs/plans		docs/plans
lib		lib
npm		npm
scripts		scripts
test		test
.gitignore		.gitignore
.pubignore		.pubignore
CHANGELOG.md		CHANGELOG.md
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

ULink CLI

AI-Assisted Setup (Recommended)

Installation

npm (zero-install)

Quick Install (script)

Install Specific Version

For Dart Developers

Manual Download

Quick Start

Commands

ulink login

ulink logout

ulink project set

ulink project show

ulink api-keys

ulink verify

ulink fix

ulink import firebase

ulink resolve

ulink version