mastodon-cli

A command-line client for the Mastodon API and compatible fediverse servers (snac2 and others), built for screen-reader / keyboard-first workflows.

⚠️ Security note: your access token and OAuth client secret are stored in plaintext JSON at %APPDATA%\mastodon-cli\config.json (Windows) or ~/.config/mastodon-cli/config.json (Linux/macOS). The installer locks file permissions to the current user; treat that file like a password. Never commit it, and never share it.

Features

• Line-based timeline — timeline, next, prev, view <n>, rs (replies via the status context endpoint, works on snac2)
• Interact — reply, boost, fav, bm, hide/unhide
• Media — gf <n|rK|id> downloads attachments to ~/Downloads
• Translate — t [<n>] <lang> (e.g. t en, t 3 de) via the no-key Google endpoint
• Account + moderation — follow, block, mute, hb, search, suspend, unsuspend, delete
• Automations — save reusable commands with automate --name=X -c "..."
• 1-based numbering everywhere — no more #0

Install

Requires Python 3.9+. With uv:

uv tool install .
mastodon-cli

Or with pip:

pip install .
mastodon-cli

Or run straight from source:

uv run mastodon-cli

Setup

mastodon-cli 0.1.0
type 'help' for commands, 'quit' to exit.
mastodon-cli> auth
1: OAuth code flow (any server, incl. snac2)
2: Access token (Mastodon dev menu)

Choose 1 for the full OAuth flow (works on snac2), or 2 to paste an access token from your instance's Preferences → Development menu. The token is stored in your user config dir (see security note above).

Usage

mastodon-cli> timeline
Showing 1-10 of 10 loaded
#1
Bob  [bob@mastodon.social]
Hello world!
  id=1093...  3 favs 1 boosts 0 replies
----------------------------------------------------------------------------
#2
...

Commands: view <n>  next  prev  rs [n]  gf <n|id>  hide <n|rK|id>  unhide <n|id>  t <lang>  reply|boost|fav|bm <n|rK|id>  quit

Run help inside the shell for the full command reference.

Compatibility

• Mastodon (4.x) — full API support.
• snac2 — works; snac reports a fake Mastodon version and omits OAuth scope, both handled. hide falls back to local-only (snac's conversation mute route is an empty stub), and admin commands are detected as unavailable.

License

GPL-3.0 — see LICENSE.