🔥 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 - --json on every command, plain output when piped, NO_COLOR honored, 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> --help for 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

--json on 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