git:20260522.5bb8440 to git:20260711.a5f7e74

---

name: peertube

license: MIT

metadata:

---

# 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:

```bash

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

```

2. (Optional) Log in for authenticated operations:

```bash

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

```bash

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

```bash

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

```bash

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

```bash

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

```bash

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

```bash

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:

```bash

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](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](https://docs.joinpeertube.org/api/reference) — Official API reference.

- [JoinPeerTube.org](https://joinpeertube.org/) — Find instances and learn about the federated video platform.