While Fedify is primarily known as a framework for building ActivityPub servers, it also comes with a powerful command-line tool called fedify for debugging and testing ActivityPub implementations. Whether you're using the Fedify framework or not, this CLI tool can be invaluable for ActivityPub development.
Installation
Before diving into the features, you'll need to install the fedify command. You have several options:
Using npm (Node.js):
npm install -g @fedify/cli
Using Bun:
bun install -g @fedify/cli
Using Deno:
deno install -A --unstable-fs --unstable-kv --unstable-temporal -n fedify jsr:@fedify/cli
You can also download pre-built executables from the releases page.
For more detailed installation instructions and requirements, see the official documentation.
Smart Object Lookup
The fedify lookup command is smarter than it looks—it can handle various formats of the same identifier and provides multiple output formats to suit your needs:
# Three equivalent ways to look up the same actor:
fedify lookup @user@example.com
fedify lookup user@example.com
fedify lookup acct:user@example.com
# View the raw JSON response:
fedify lookup --raw @user@example.com
# Get a compact JSON-LD representation:
fedify lookup --compact @user@example.com
# See the fully expanded JSON-LD:
fedify lookup --expanded @user@example.com
Some ActivityPub servers require authorized fetch (also known as “secure mode”), which means all HTTP GET requests must be signed—even for public content. The -a/--authorized-fetch flag helps with this:
fedify lookup --authorized-fetch @user@secure-instance.example
This spins up a temporary ActivityPub server and signs the request with its key. This is particularly useful when:
- Accessing servers that require signatures for all requests (like certain Mastodon instances in secure mode)
- Fetching non-public content like followers-only posts (assuming you have permission)
- Testing how your server behaves with signed requests
Interactive Inbox Testing
The fedify inbox command not only provides a quick way to test federation but also comes with a powerful web interface for inspecting incoming ActivityPub activities. When you receive an activity, it shows you everything about the request, including:
- HTTP method and headers
- Request body (in multiple formats)
- Response details
- Server logs
You can see the raw HTTP headers that other servers send, which is invaluable when debugging signature verification issues or content negotiation problems. The interface includes tabs for viewing the activity in different formats:
- Raw HTTP request/response
- Compact Activity (normalized JSON-LD)
- Expanded Activity (fully expanded JSON-LD)
- Raw Activity (as received)
- Server logs
The command is highly configurable—you can control which follow requests to accept:
# Only accept follows from specific actors
fedify inbox -a @specific@user.com -a @another@user.com
# Accept all follow requests
fedify inbox -a "*"
Rich NodeInfo Visualization
The fedify node command helps you understand how other instances are configured by visualizing their NodeInfo data in a user-friendly format:
# Show standard NodeInfo data with server icon
fedify node mastodon.social
# Include extra metadata that instances expose
fedify node -m mastodon.social
# Try to parse non-compliant NodeInfo responses
fedify node --best-effort problematic-instance.social
# Skip favicon fetching for faster results
fedify node --no-favicon mastodon.social
Flexible Local Development
For testing your ActivityPub implementation locally, the fedify tunnel command lets you temporarily expose your local server to the internet. You can choose from multiple tunneling services if the default one isn't working well:
# Use the default service
fedify tunnel 3000
# Use an alternative service
fedify tunnel --service serveo.net 3000
Shell Integration
Save yourself some typing by enabling shell completions—available for bash, fish, and zsh:
# For bash
source <(fedify completions bash)
# For fish
source (fedify completions fish | psub)
# For zsh
source <(fedify completions zsh)
Coming in Fedify 1.3.0: Custom User-Agent Support
The upcoming Fedify 1.3.0 release will include a feature to set custom User-Agent headers, which is helpful for tracking your requests in server logs:
# Set a custom User-Agent for lookup
fedify lookup --user-agent "MyApp/1.0" @user@example.com
# Set a custom User-Agent for NodeInfo requests
fedify node --user-agent "MyApp/1.0" mastodon.social
These features might not be immediately obvious when you first start using the Fedify CLI, but they can be incredibly helpful when debugging federation issues or testing your ActivityPub implementation.
Top comments (0)