taibai

Fediverse CLI tool — celestial messenger for the federation.

Taibai (太白金星, Tàibái Jīnxīng — "Gold Star of Venus") is the celestial herald in Chinese mythology, tasked with carrying messages between heaven and earth. The name fits a tool that sends and receives communications across a federated network, and continues the Chinese mythology theme of its companion library longwei (龙威).

Built on longwei.

Documentation: https://marvinsmastodontools.codeberg.page/taibai/latest/

Install

uv tool install taibai

Usage

taibai init                               # authenticate with a Fediverse instance
taibai init --instance URL --token TOKEN  # headless / non-interactive setup
taibai whoami                        # display current account
taibai token                         # print stored access token (for CI/CD secrets)
taibai post "Hello, world!"          # publish a status
taibai post "Reply!" --reply-to ID   # reply to a status (chain with --json | jq for threads)
taibai notifications                 # show new notifications
taibai timeline                      # home timeline (public/tag/list also supported)
taibai view 123456789012345678        # view a status or thread (--context for full thread)

taibai fav ID                        # favourite a status
taibai boost ID                      # boost a status
taibai bookmark ID                   # bookmark a status
taibai pin ID                        # pin a status to your profile
taibai delete ID                     # delete a status
taibai edit ID "New text."           # edit a status

taibai bookmarks                     # list your bookmarks
taibai favourites                    # list your favourites

taibai follow user@instance.social   # follow an account
taibai unfollow user@instance.social
taibai mute user@instance.social     # mute (optional --duration SECS, --no-notifications)
taibai unmute user@instance.social
taibai block user@instance.social
taibai unblock user@instance.social
taibai profile user@instance.social  # view profile + recent posts
taibai search "climate change"       # search statuses, accounts, and hashtags
taibai search python --type accounts --resolve

taibai thread my-thread.md           # post a thread from a file
taibai thread-download URL           # download a thread to stdout (--format thread|json|markdown)

taibai completions bash              # print bash completion script (eval or source)

All data-returning commands accept --json to dump output as JSON instead of a Rich table or panel.

Use --profile / -p (or TAIBAI_PROFILE env var) to manage multiple accounts.

License

AGPL-3.0-or-later