malachite
web v0.2.0 – cli v0.9.3
← Back

About Malachite

Privacy & data

No tracking
No accounts
No server storage

Malachite runs entirely in your browser. Your export files are parsed locally — they are never uploaded to any server run by this project.

The only network requests made are:

  • Slingshot (slingshot.microcosm.blue) — resolves your ATProto handle to a DID and PDS URL. This is a standard identity lookup, equivalent to a DNS query. No personally identifiable data beyond your handle is sent.
  • Your PDS — Malachite authenticates directly with your Personal Data Server and publishes records there on your behalf, exactly as any other ATProto client would. Your app password is used only for this request and is never stored or logged.
  • Google Fonts — the layout loads Inter and JetBrains Mono via Google Fonts. If you prefer not to make this request, you can self-host the fonts or use a content-blocking extension.

No analytics, no cookies, no local storage, no fingerprinting.

CLI / Local usage

Malachite also ships as a Node.js command-line tool. This is useful if you prefer to run imports locally, need full control over batch settings, or want to automate things with scripts.

Prerequisites

  • Node.js v18 or later
  • pnpm (recommended) — or npm / yarn

Install & build

# Clone the repository
git clone https://github.com/ewanc26/malachite.git
cd malachite

# Install dependencies
pnpm install

# Build
pnpm build

Interactive mode

Run without arguments and Malachite will walk you through everything:

pnpm start

Command-line mode

Common invocations:

# Import from Last.fm CSV
pnpm start -i lastfm.csv -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y

# Import from Spotify JSON export
pnpm start -i spotify-export/ -m spotify -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y

# Merge both sources
pnpm start -i lastfm.csv --spotify-input spotify-export/ -m combined -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y

# Sync (skip already-imported records)
pnpm start -i lastfm.csv -m sync -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y

# Remove duplicates from your Teal feed
pnpm start -m deduplicate -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx

# Preview without publishing
pnpm start -i lastfm.csv --dry-run

Key flags

FlagDescription
-i <path>Input file or directory
-h <handle>ATProto handle or DID
-p <password>App password (not your main password)
-m <mode>lastfm · spotify · combined · sync · deduplicate
-ySkip confirmation prompts
--dry-runPreview without writing records
-vVerbose / debug output
-qQuiet mode (warnings & errors only)

Full documentation is available at docs.ewancroft.uk/projects/malachite.

Rate limits & PDS safety

ATProto PDS instances enforce rate limits on write operations. Exceeding them can temporarily affect all users on a shared PDS. Malachite protects against this by:

  • Reading the ratelimit-* headers from each response
  • Maintaining a 15% headroom buffer before the quota ceiling
  • Automatically adjusting batch size (up to 200 records) in real time
  • Pausing immediately when the abort signal fires if you press Stop

Licence

Malachite is free software released under the GNU Affero General Public License v3.0 (AGPL-3.0-only).

In short: you are free to use, modify, and redistribute this software, but any modified version you run as a network service must also be released under the same licence with its source code made available.

The full licence text is included in the repository.

Credits

Created by

Ewan Croft Author & maintainer
GitHub Ko-fi Website

Contributors

Contributions via GitHub are always welcome. The full contributor list is maintained there.

Dependencies