README
¶
🔥 Features 📦 Installation 🚀 Quick Start 📋 Commands 🤝 Contributing
🔥 Features
No-Account Shortening- Create short links without signing in ⚡Interactive Shorten- Custom alias with live availability check, password, max clicks, expiry, bot blocking, and--qr🎛️Links Browser (TUI)- Navigate, open, copy, edit, archive, and delete every link with a live analytics sidebar ✏️Analytics Dashboard- Terminal charts: traffic over time with a previous-period overlay, browser/OS/country/city/referrer panels, drill-down filtering, range expressions, and full mouse support 📊QR Codes- Render any link as a scannable QR code right in the terminal 📱Export- Download click data as JSON, CSV, XLSX, or XML 📤API Keys- Create, list, and revoke keys for scripting 🔑Device-Flow Auth- No keys to paste — sign in through the spoo.me device flow, sessions refresh for 30 days 🪪Pipe-Aware---jsonon every command, plain output when piped,NO_COLORhonored, self-host friendly 🧰
📦 Installation
Homebrew (macOS / Linux)
brew install spoo-me/tap/spoo
Scoop (Windows)
scoop bucket add spoo-me https://github.com/spoo-me/scoop-bucket
scoop install spoo
Go
go install github.com/spoo-me/spoo-cli/cmd/spoo@latest
Binary & Linux packages
Grab a binary for macOS, Linux, or Windows — or a .deb, .rpm, or .apk package — from the releases page.
[!TIP] Point the CLI at a self-hosted instance any time with
export SPOO_API_URL=http://localhost:8000.
⌨️ Shell Completion
Tab-completion covers commands, flags, and live data — your link aliases (spoo open <Tab>), link and key IDs (spoo links delete <Tab>, spoo keys revoke <Tab>), and flag values like --scopes, --domain, and --format.
Installed via Homebrew? It's wired up automatically — just open a new shell.
Installed another way (go install, a raw binary, Scoop, or a Linux package)? Load it for your shell:
source <(spoo completion zsh) # zsh — add to ~/.zshrc
source <(spoo completion bash) # bash — add to ~/.bashrc
spoo completion fish | source # fish
spoo completion powershell | Out-String | Invoke-Expression # PowerShell — add to $PROFILE
[!NOTE] Run
spoo completion <shell> --helpfor instructions on installing the script permanently.
🚀 Quick Start
spoo shorten https://example.com/very/long/path # works without an account
spoo auth login # browser one-click authorization
spoo shorten # interactive form
cat urls.txt | spoo shorten # bulk
spoo links # interactive link browser (TUI)
spoo stats launch # charts in your terminal
📋 Commands
| Command | What it does |
|---|---|
spoo shorten [url] |
Create a link — flags for alias, password, max clicks, expiry, bot blocking, and --qr to print a scannable code. Interactive form with live alias availability when run bare. |
spoo links |
Interactive TUI browser: navigate, open, copy, edit (e, pre-filled form), archive/activate (t), delete (d, type-the-alias confirm), QR (Q). --json or piping prints the list instead. ? shows all keys. |
spoo links update/delete <id> |
Scriptable link management (delete requires --yes). |
spoo stats [code] |
Interactive analytics dashboard: time chart with previous-period overlay (p), browser/OS/country/city/referrer panels, drill-down filtering (enter or click any row), link switcher (g), range expressions (T — 7d, 4h, now - 2w to now - 1w, 2026-01-01 to 2026-02-15), clicks↔unique toggle (u), full mouse support. Piped or --plain prints a static report; public stats work logged out. |
spoo export [code] |
Download analytics as JSON, CSV (zip), XLSX, or XML. |
spoo keys |
API keys: create (token shown once), list, revoke. |
spoo open <code> |
Open a short link in your browser. |
spoo inspect <code> |
See where a link points without counting a click. |
spoo qr <code> |
Render a link as a scannable QR code in the terminal (also Q in spoo links). |
spoo auth login/logout/status, spoo whoami |
Account session. |
[!NOTE]
--jsonon any command emits machine-readable output. Output is pipe-aware: styled on a terminal, plain when piped.
🔑 Authentication
Sign in with the connected-apps device flow — your browser opens, you approve once, and the CLI receives scoped tokens. It never sees your password, and sessions refresh themselves for 30 days:
spoo auth login
Manage or revoke access any time at https://spoo.me/dashboard/apps.
Headless or CI? Skip the browser and pipe in an API key from https://spoo.me/dashboard/keys:
echo $SPOO_TOKEN | spoo auth login --with-token
🛠️ Development
go build ./... # build
go test ./... # test (no network, no real keychain)
Releases are cut by pushing a v* tag; GoReleaser builds and publishes every platform binary.
🤝 Contributing
Issues and pull requests are welcome. Found a bug or have an idea? Open an issue or join the conversation on Discord.
© spoo.me . 2026
All Rights Reserved
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
spoo
command
|
|
|
internal
|
|
|
api
Package api is a typed client for the spoo.me HTTP API.
|
Package api is a typed client for the spoo.me HTTP API. |
|
auth
Package auth manages spoo CLI credentials and the device-auth login flow.
|
Package auth manages spoo CLI credentials and the device-auth login flow. |
|
config
Package config resolves spoo CLI configuration and filesystem paths.
|
Package config resolves spoo CLI configuration and filesystem paths. |
|
tui/kit
Package kit holds the shared Bubble Tea widgets and rendering primitives used by the stats and links screens.
|
Package kit holds the shared Bubble Tea widgets and rendering primitives used by the stats and links screens. |
|
tui/links
Package tui contains the interactive Bubble Tea views.
|
Package tui contains the interactive Bubble Tea views. |
|
ui
Package ui holds the lipgloss styles shared by every spoo command, so CLI output and future TUI views render with one visual language.
|
Package ui holds the lipgloss styles shared by every spoo command, so CLI output and future TUI views render with one visual language. |