Fedify CLI Specification Guide

Complete reference to the Fedify CLI toolchain for building, testing, and debugging ActivityPub-enabled federated server applications. Essential tools for fediverse development and integration.

📋 Executive Summary

Purpose and Overview

The Fedify CLI (`fedify`) is a comprehensive command-line toolchain designed for building, testing, and debugging ActivityPub-enabled federated server applications. While primarily designed for developers using the Fedify framework, it provides universal utilities that work with any ActivityPub-enabled server.

Core Functionality:

Project Initialization: Scaffolding new Fedify projects
ActivityPub Debugging: Object and actor inspection
Development Testing: Ephemeral server creation
Network Utilities: Tunneling and WebFinger discovery
Instance Analysis: NodeInfo visualization

Key Components

Project Generator

Interactive project scaffolding with multiple runtime options

Object Inspector

Comprehensive ActivityPub object lookup and analysis

Ephemeral Server

Temporary ActivityPub server for testing federation

Network Tools

Secure tunneling and WebFinger discovery utilities

🚀 Installation and Setup

Prerequisites

Node.js 18.0 or later
npm, yarn, pnpm, or bun package manager
Git for version control
Optional: Docker for containerized development

Installation Methods

Global Installation

npm install -g @fedify/cli

Project-specific

npx @fedify/cli [command]

Package Manager

yarn global add @fedify/cli
pnpm add -g @fedify/cli

⚡ Command Reference

Project Management

`fedify init`

Initialize a new Fedify project with interactive setup

--runtime - Choose runtime (Node.js, Deno, Bun)
--framework - Select framework integration
--template - Use predefined template

`fedify dev`

Start development server with hot reloading

--port - Specify port number
--host - Set host address
--tunnel - Enable public tunneling

ActivityPub Debugging

`fedify lookup`

Look up ActivityPub objects, actors, and collections

--format - Output format (json, typescript, raw)
--follow - Follow redirects
--headers - Show HTTP headers

`fedify webfinger`

Perform WebFinger resource discovery

--resource - Target resource identifier
--rel - Filter by relationship type

Testing & Development

`fedify ephemeral`

Create temporary ActivityPub server for testing

--duration - Server lifetime
--actors - Number of test actors
--activities - Generate test activities

`fedify tunnel`

Create secure tunnel to local development server

--port - Local port to tunnel
--subdomain - Custom subdomain
--auth - Enable authentication

Instance Analysis

`fedify nodeinfo`

Analyze and visualize NodeInfo data

--instance - Target instance URL
--format - Output format
--stats - Include usage statistics

`fedify federation`

Test federation capabilities and connectivity

--target - Target instance
--activity - Test activity type
--timeout - Request timeout

🏗️ Project Scaffolding

Runtime Options

Node.js

Traditional Node.js runtime with npm ecosystem

Express.js integration
TypeScript support
Rich middleware ecosystem

Deno

Modern runtime with built-in TypeScript and security

Native TypeScript
Built-in testing
Secure by default

Bun

Fast all-in-one JavaScript runtime and toolkit

Ultra-fast performance
Built-in bundler
Native package manager

Framework Integration

Standalone

Pure Fedify implementation without additional frameworks

Express.js

Integration with Express.js web framework

Fastify

High-performance web framework integration

Hono

Lightweight web framework for edge computing

🔧 Development Workflow

1. Project Initialization

fedify init my-activitypub-server
cd my-activitypub-server

Creates a new project with interactive configuration

2. Development Server

fedify dev --tunnel

Starts development server with public tunnel for federation testing

3. Testing Federation

fedify ephemeral --actors 5 --activities 10

Creates temporary test environment for federation testing

4. Debugging Objects

fedify lookup https://mastodon.social/@user

Inspects ActivityPub objects and actors across the fediverse

🔗 Integration with ActivityPub MCP Server

Development Tools

The Fedify CLI provides essential development tools for building and testing ActivityPub applications that integrate with our MCP server.

Object inspection for debugging MCP tool outputs
Federation testing for server-to-server communication
WebFinger discovery for actor resolution
Ephemeral servers for testing LLM-generated activities

LLM Development Workflow

Streamlined workflow for developing LLM applications with ActivityPub integration.

Rapid prototyping with scaffolded projects
Real-time testing with tunneled development servers
Automated federation testing for AI-generated content
Debugging tools for ActivityPub object validation