URL Shortener TUI
A terminal-first Python application for creating, managing, and serving short links with a built-in redirect server, searchable workflows, and multi-backend persistence.
Type
Open source developer tool
Stack
Python, Textual, uv, pyperclip
Storage
SQLite by default, with PostgreSQL and MySQL support
Started
March 2026
Overview
This project started from a simple question: what would a URL shortener built for the terminal feel like if it treated developer ergonomics as the primary interface?
Instead of a browser dashboard, the app uses a polished Textual TUI to handle the full lifecycle of a short link:
- Create short URLs with random or custom codes
- Browse and search links in a table-driven workflow
- Inspect details, click counts, and timestamps
- Edit and delete links with confirmation steps
- Serve live redirects from the same application
Why I Built It
Most URL shorteners are web products first. I wanted to explore a different interaction model: a keyboard-centric developer tool that can be launched locally, managed quickly, and still expose a real HTTP redirect endpoint.
The project also became a good vehicle for exercising a clean application boundary between domain logic, persistence, and user interface concerns.
Key Features
- Built-in redirect server for `GET /<code>` to destination redirects
- Searchable data table for fast link discovery
- Clipboard support for sharing generated short URLs quickly
- Configurable base URL, port, theme, and server behaviour
- Universal help modal to keep workflows discoverable from inside the TUI
- Cryptographically secure code generation using `secrets.choice()`
Help and Discoverability
A built-in help modal documents the keyboard shortcuts and core operations directly inside the app, which keeps the interface learnable without forcing users out to separate documentation.
Architecture Decisions
Terminal UI with Textual
Textual made it possible to build a rich, responsive interface without abandoning the terminal. That gave the app a native-feeling workflow for power users while keeping distribution simple.
Built-In Redirect Serving
The redirect server is part of the product, not an afterthought. That means link management and link resolution stay tightly aligned, including click tracking and base URL configuration.
Repository Pattern for Storage
Persistence is intentionally abstracted behind repository interfaces, allowing the same workflow to run against SQLite locally or PostgreSQL/MySQL when a different deployment profile is needed.
Developer Experience
The project is built around a clean local development loop using uv for dependency management and execution. The default path is intentionally lightweight:
- `uv sync --dev` to provision the environment
- `uv run python run.py` to launch the TUI
- `uv run python -m pytest -q` to run tests
- Optional Docker Compose profiles for backend-specific setups
What Makes It Distinct
- It treats the terminal as the primary product surface rather than a secondary admin tool
- It combines link management and redirect serving in one coherent application
- It stays practical for local use while still supporting more serious database backends
- It focuses on usability details such as help states, search, settings, and clipboard integration
Related Links
- Repository: github.com/vincyf1/url-shortener
- Topics: Python, Textual, terminal UI, URL shortener, developer tools