Installing the `skyscraper` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install skyscraper-cli

It will make the skyscraper command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall skyscraper-cli uninstalls.

Back to the crate overview.

Readme

Skyscraper

A tool for deleting old posts from Bluesky and Mastodon.

Posts older than a configurable retention period (default: 180 days) are deleted automatically. A keep list lets you exempt specific posts.

Installation

Homebrew (macOS and Linux)

brew install ZacSweers/tap/skyscraper

Shell installer (macOS and Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/ZacSweers/skyscraper/releases/latest/download/skyscraper-cli-installer.sh | sh

PowerShell installer (Windows)

powershell -ExecutionPolicy ByPass -c "irm https://github.com/ZacSweers/skyscraper/releases/latest/download/skyscraper-cli-installer.ps1 | iex"

Cargo

cargo install skyscraper-cli

GitHub Releases

Download prebuilt binaries from the latest release.

GitHub Action

Use skyscraper in your own GitHub Actions workflow without installing anything:

name: Skyscraper

on:
  schedule:
    - cron: '0 6 * * *'
  workflow_dispatch:

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6 # Only if you need keep-path
      - uses: ZacSweers/skyscraper@v1
        with:
          bluesky-identifier: ${{ secrets.BLUESKY_IDENTIFIER }}
          bluesky-app-password: ${{ secrets.BLUESKY_APP_PASSWORD }}
          mastodon-instance-url: ${{ secrets.MASTODON_INSTANCE_URL }}
          mastodon-access-token: ${{ secrets.MASTODON_ACCESS_TOKEN }}
          keep: |
            bluesky:3k2la5diqyc2x
            mastodon:111234567890123456
          keep-path: path/to/keep.txt

Setup

1. Generate tokens

You can run the setup-tokens.sh script in this repo to generate and configure all tokens interactively:

./setup-tokens.sh

The script walks you through each platform, validates credentials, and optionally writes them as GitHub Actions secrets via gh secret set.

If you prefer to do it manually, see Manual token setup below.

2. Configure the keep list

Edit keep.txt to protect posts from deletion. One entry per line:

# Bluesky — use the rkey (last segment of the AT URI) or the full URI
bluesky:3k2la5diqyc2x
bluesky:at://did:plc:xyz/app.bsky.feed.post/3k2la5diqyc2x

# Mastodon — use the status ID
mastodon:111234567890123456

Lines starting with # and blank lines are ignored.

Environment variables

Required (per platform)

Any platform whose variables are missing is silently skipped.

Variable	Description
`BLUESKY_IDENTIFIER`	Your handle (e.g. `user.bsky.social`) or DID
`BLUESKY_APP_PASSWORD`	App password — generate one at bsky.app → Settings → App Passwords
`MASTODON_INSTANCE_URL`	Instance base URL, e.g. `https://mastodon.social`
`MASTODON_ACCESS_TOKEN`	OAuth access token from your instance's developer settings

Optional

Variable	Default	Description
`RETENTION_DAYS`	`180`	Posts older than this many days are deleted
`DRY_RUN`	`false`	Set to `true` to log what would be deleted without actually deleting
`BLUESKY_PDS_HOST`	`https://bsky.social`	Override if your account is on a different PDS
`KEEP_FILE`	`keep.txt`	Path to the keep list file
`DELETE_REPOSTS`	`true`	Set to `false` to skip deleting reposts/reblogs
`DELETE_LIKES`	`true`	Set to `false` to skip deleting likes/favourites
`DELETE_PINNED`	`false`	Set to `true` to delete pinned posts instead of skipping them

Rate limits

Mastodon enforces a rate limit of 30 status deletions per 30 minutes (this includes unfavourites and unreblogs). If you have many old posts, the first run may hit 429 (Too Many Requests) errors after the first 30 deletions. Failed deletions are logged as warnings and skipped — subsequent runs will pick up where the previous run left off. Running on a daily cron schedule (as shown in the GitHub Action example) will steadily clear the backlog.

Manual token setup

Bluesky

Go to bsky.app → Settings → App Passwords.
Create a new app password (name it something like "skyscraper").
Set BLUESKY_IDENTIFIER to your handle and BLUESKY_APP_PASSWORD to the generated password.

Mastodon

Log into your instance's web UI.
Go to Preferences → Development → New Application.
Set the application name (e.g. "skyscraper").
Required scopes: read:accounts, read:statuses, write:statuses.
Save, then copy the access token.
Set MASTODON_INSTANCE_URL to your instance URL and MASTODON_ACCESS_TOKEN to the token.

Running locally

# Dry run (no deletions)
DRY_RUN=true BLUESKY_IDENTIFIER=you.bsky.social BLUESKY_APP_PASSWORD=xxxx cargo run

# Real run
BLUESKY_IDENTIFIER=you.bsky.social BLUESKY_APP_PASSWORD=xxxx cargo run

License

Copyright (C) 2026 Zac Sweers

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Installing the skyscraper executable

Installing the `skyscraper` executable