Skip to content

V2Hub CLI

Beautiful, user-friendly command-line interface for the V2Hub VPN Subscription API, built on top of the v2hub Python client, with optional admin commands.

pip install v2hub-cli

export V2HUB_API_URL="https://api.example.com"
export V2HUB_API_TOKEN="your-api-token"

v2hub list
v2hub create "my-vpn" -s vless://uuid@server1:443#Server1

Features

  • 🎨 Beautiful output — Rich-formatted tables and panels
  • ⚡ Tab completion — commands, options, and real values (tokens, hashes, IPs) pulled live from the API
  • 🔧 Regular commands — full self-service subscription management
  • 🤝 Provider commands — manage subscriptions on behalf of end-users (v2hub provider <user_id> ...)
  • 🔐 Admin commands — optional, requires v2hub-admin: users, providers, authorizations, IP bans, whitelist, stats
  • 🎯 Type safe — built on Typer, full type hints

Documentation

Page Covers
Installation Installing the package, with and without admin support
Configuration & Authentication Environment variables, --base-url/--api-token, admin's --secret-key, resolution order
Shell Autocompletion Automatic setup, manual install, dynamic value completion, opting out
Subscription Commands list, create, get, update, update-config, add/replace/remove-sources, delete, refresh, me, public
Connection Commands Managing the current user's connections to providers
Provider Commands v2hub provider <user_id> ... — acting on behalf of an end-user
Admin Commands Users, providers, authorizations, IP bans, whitelist, usage stats
Common Workflows & Examples End-to-end examples for everyday tasks
Command Reference Flat, alphabetized index of every command

Requirements

  • v2hub (required, installed automatically) >=1.1.2,<2.0.0
  • v2hub-admin >=1.1.4,<2.0.0 (optional, for admin commands)
  • Python >=3.10

Extensions

  • v2hub — the underlying Python client library.
  • v2hub-admin — admin API extension; installing it unlocks v2hub admin ....

Development

git clone https://github.com/nestthub/v2hub-cli.git
cd v2hub-cli
pip install -e ".[admin,dev]"

pytest              # run tests
mypy src/           # type checking
ruff check src/     # linting

License

MIT License — see the LICENSE file for details.