Getting Started¶

Installation¶

uv tool install taibai

Alternatively, with pipx:

pipx install taibai

Connecting an account¶

Run taibai init to register the app with your Fediverse instance and complete the OAuth flow. No API keys need to be obtained in advance — taibai handles app registration automatically.

taibai init

The command walks you through three steps:

Step 1 — Enter your instance URL

Instance URL (e.g. https://mastodon.social):

Step 2 — Open the authorisation URL in your browser

taibai prints a URL. Open it, grant permission to the app, and copy the authorisation code shown on screen.

Step 3 — Paste the code

Paste the authorization code:

On success, a confirmation panel is printed and your credentials are saved locally:

╭─ Connected ───────────────────────────╮
│ @youruser@mastodon.social             │
│ https://mastodon.social               │
╰───────────────────────────────────────╯
Profile 'default' saved.

Your access token is stored in the OS keyring where available. On headless systems without a keyring daemon, the token falls back to a plaintext config file at ~/.config/taibai/config.json — protect that file accordingly.

Options¶

Option	Short	Env	Default	Description
`--instance`	`-i`	—	prompted	Fediverse instance URL
`--profile`	`-p`	`TAIBAI_PROFILE`	`default`	Profile name to save credentials under

Pass --instance to skip the prompt:

taibai init --instance https://fosstodon.org

Checking your account¶

taibai whoami verifies your credentials and displays account details.

taibai whoami

Example output:

╭─ @youruser@mastodon.social ───────────────────────────────╮
│ Display name  Your Name                                   │
│ Followers     1 234                                       │
│ Following     567                                         │
│ Posts         4 321                                       │
│ Locked        No                                          │
│ Bot           No                                          │
│ URL           https://mastodon.social/@youruser           │
╰───────────────────────────────────────────────────────────╯

Options¶

Option	Short	Env	Default	Description
`--profile`	`-p`	`TAIBAI_PROFILE`	`default`	Profile to use

Multiple profiles¶

Every command accepts --profile / -p (or the TAIBAI_PROFILE environment variable) to select which account to use. This makes it straightforward to manage multiple Fediverse accounts.

Create a second profile:

taibai init --profile work

Use it for a command:

taibai post "Posting from the work account." --profile work
taibai notifications --profile work

Switch the active profile for an entire shell session via the environment variable:

export TAIBAI_PROFILE=work
taibai whoami
taibai notifications

Profile data is stored in ~/.config/taibai/config.json. Each profile tracks its own instance URL, app credentials, and notification read state independently.

CI / headless usage¶

For automated pipelines (GitHub Actions, GitLab CI, etc.) where there is no interactive setup and no keyring, you can bypass profile configuration entirely by setting two environment variables:

Variable	Description
`TAIBAI_INSTANCE_URL`	Your Mastodon instance base URL (e.g. `https://mastodon.social`)
`TAIBAI_ACCESS_TOKEN`	A pre-generated API access token

Both variables must be set together. Setting only one is an error.

Generate an access token from your Mastodon web interface under Preferences → Development → New application. Grant the scopes your workflow needs (read, write, etc.) and copy the token into your CI secrets store.

Example GitHub Actions step:

- name: Post release announcement
  env:
    TAIBAI_INSTANCE_URL: ${{ secrets.MASTODON_INSTANCE_URL }}
    TAIBAI_ACCESS_TOKEN: ${{ secrets.MASTODON_ACCESS_TOKEN }}
  run: taibai post "Version 1.0 is out! 🎉"

No taibai init or config file is required when both variables are present.

Note: When using env-var auth, the notifications command cannot track which notifications you have already seen (there is no stored profile to persist the read position). It will always show all notifications since the --all flag was passed, unless you also set --since-id explicitly.