Peertube

peertube-cli — PeerTube Federated Video

Browse videos, channels, and server info on any PeerTube instance. Search across the fediverse, list channels, check your account stats, and manage authentication — all from the terminal.

Setup

1. Set the PeerTube instance URL:

export PEERTUBE_SERVER="https://your-instance.example.com"

2. (Optional) Log in for authenticated operations:

peertube-cli auth login --username "your-username" --password "your-password"

The OAuth2 token is persisted to ~/.config/peertube-cli/token.json and automatically reused. --dry-run works without authentication.

Essential Commands

auth login — Authenticate to a PeerTube instance

peertube-cli auth login --username "myuser" --password "mypassword"   # login

Token is saved to ~/.config/peertube-cli/token.json and reused on subsequent calls. Tokens expire after the server-configured lifetime (typically 24h).

server — Instance information

peertube-cli server                                # instance name, description, stats
peertube-cli server --json                         # machine-readable

Shows: instance name, short description, total users, total videos, total views.

videos — Browse recent videos

peertube-cli videos                                # last 12 videos
peertube-cli videos --limit 24                     # more results
peertube-cli videos --json                         # machine-readable

Shows: title, duration, views, author/channel, publish date.

search — Search videos across the fediverse

peertube-cli search --query "linux tutorial"       # search videos
peertube-cli search -q "peer" --limit 24           # more results
peertube-cli search -q "docker" --json             # machine-readable

channels — List video channels

peertube-cli channels                              # all channels on the instance
peertube-cli channels --json                       # machine-readable with subscriber counts

Shows: display name, channel handle (@name), video count, subscriber count.

me — Your profile

peertube-cli me                                    # your account stats
peertube-cli me --json                             # machine-readable

Shows: username, role, video count, view count. Requires authentication.

Global Flags

All flags work in any position:

peertube-cli --json videos                         # flag before subcommand
peertube-cli videos --json                         # flag after subcommand
peertube-cli --dry-run search --query "test"       # preview (no API call)
peertube-cli --quiet videos                        # suppress non-essential output
peertube-cli --verbose channels                    # detailed logging

Known Gotchas

• Set PEERTUBE_SERVER first — Without this env var, the CLI defaults to https://your-instance.example.com (which won't resolve). Always export the correct instance URL.
• Authentication is required for most commands — server and public video browsing work without auth. me, channels, and personal video lists require a valid OAuth token. Use --dry-run to preview without auth.
• Token is persisted automatically — After auth login, the token is saved to ~/.config/peertube-cli/token.json. No need to login again unless the token expires. Delete this file to force re-login.
• Token expiry — PeerTube OAuth2 tokens have a configurable expiry (default ~24h). Expired tokens cause 401 errors. Re-run auth login to refresh.
• Cross-instance search — search --query searches across the fediverse, not just the local instance. Results may include videos from remote instances.
• API pagination — PeerTube uses offset-based pagination. The --limit flag controls the page size (default: 12 for videos, 15 for channels).
• Rate limits — PeerTube instances have configurable rate limits. The CLI does not auto-retry on 429 responses.

References

• scripts/peertube-cli — The CLI binary. Built following the cli-builder patterns: --json, --dry-run, --quiet, --verbose, dual-output via emit(), lazy auth, config file persistence.
• PeerTube API Reference — Official API reference.
• JoinPeerTube.org — Find instances and learn about the federated video platform.