Fediverse Emoji Manager

A terminal UI for browsing custom emoji from Mastodon and Misskey instances. It groups emoji into packs by their source category, supports Kitty-native or ANSI previews, batch selection and download, and registering files after uploading them to a chosen Misskey Drive folder.

Run

Go 1.23+ and a terminal with 24-bit color support are recommended.

cp .env.example .env
go run .
# Or start with an instance pre-filled
go run . -instance misskey.io

# Skip the source instance and upload previously downloaded packs
go run . -local ./downloads

Keys: Up/Down (or j/k) changes packs, Left/Right (or h/l) changes the preview within that pack, c edits the destination pack/category name, d downloads the entire current pack, u uploads and registers the entire current pack, and q quits. The previewed image never changes the batch scope.

Kitty is detected through KITTY_WINDOW_ID or TERM. It receives previews through the Kitty Graphics Protocol; other terminals use a true-color ANSI half-block fallback.

Each batch is saved under EMOJI_DOWNLOAD_DIR/<pack-name>/. The same pack name is automatically sent to Misskey as the category when registering the emoji. The default pack name comes from MISSKEY_EMOJI_CATEGORY.

Downloads and registrations are resumable. After every item, progress is atomically saved to <pack-name>/.emoji-progress.json. Running d again skips non-empty downloaded files and retries only missing or failed items. Running u again also skips emoji recorded as successfully registered. The progress file contains the full per-item error report, including HTTP 500 responses.

Drive upload and emoji registration are separate resume stages. A successful Drive upload stores its driveFileId before registration is attempted, so retrying a failed registration reuses the existing server file instead of uploading it again. During either operation the footer shows live item, success, skip, and failure counts.

Misskey configuration

Configuration can be stored in .env or supplied as environment variables. Environment variables take precedence. See .env.example.

• MISSKEY_URL: target instance where emoji will be registered.
• MISSKEY_ADMIN_TOKEN: admin/moderator API token with write:drive and write:admin:emoji permissions.
• MISSKEY_DRIVE_FOLDER_ID: target Drive folder ID, not its display name. Leave empty for the Drive root.
• MISSKEY_REGISTER_LIMIT: maximum successful registrations for one program run; defaults to 20.

Do not delete uploaded Drive files: Misskey references them from the registered emoji. The program never overwrites or deletes remote content; name conflicts are reported by the instance API.

APIs

• Mastodon：GET /api/v1/custom_emojis
• Misskey: POST /api/emojis (falls back to /emoji/{name}.webp when recent versions omit url)
• Misskey administration: POST /api/drive/files/create, then POST /api/admin/emoji/add

Only download and import emoji assets you have permission to use.