/fedify-cli

name: fedify-cli
description: >-
  Use the fedify CLI to inspect and debug ActivityPub servers, including
  servers built without the Fedify framework. Apply when looking up actors
  or objects, diagnosing handle discovery or federation failures, fetching
  WebFinger or NodeInfo, traversing collections or reply chains, resolving
  portable objects through gateways, testing delivery with an
  ephemeral inbox, exposing a local server through a tunnel, running a test
  relay, or scaffolding a project with fedify init. Covers installation,
  version checks, command selection, output interpretation, and remote
  effects. Use for fedify CLI tasks even outside a JavaScript project.

Fedify CLI skill ================

Use `fedify` to inspect ActivityPub servers without writing an application. The target server can use any framework. For building an application with Fedify's TypeScript APIs, use the separate `fedify` skill.

Read <https://fedify.dev/cli.md> for detailed options. The documentation is available as raw Markdown with the `.md` suffix; remove that suffix when presenting links to the user. These examples target Fedify CLI 2.5.0. If the installed version differs, its `--help` output takes precedence over these examples.

Check the command first -----------------------

~~~~ sh fedify --version fedify --help fedify lookup --help ~~~~

Check the chosen subcommand's `--help` before using version-dependent flags. Use a project-local executable when the project already provides one. In a Fedify source checkout, follow its contributor instructions and use `mise run cli -- <arguments>`.

If the command is missing, choose an installation method that fits the user's runtime. For example, with Node.js:

~~~~ sh npm install -g @fedify/cli ~~~~

Deno, Bun, Homebrew, Scoop, mise, and standalone executables are covered at <https://fedify.dev/cli.md#installation>. Installing the CLI executable and installing this skill are separate steps; see <https://fedify.dev/install.md#agentic-skill>.

Configuration files can supply defaults, including options that contact remote servers. Inspect relevant defaults before running diagnostics. For an isolated invocation, put `--ignore-config` before the subcommand:

~~~~ sh fedify --ignore-config lookup @alice@example.com ~~~~

The domains and handles below are placeholders. Substitute the user's target. Discovery and lookup commands contact remote servers and may appear in their logs. Traversal fetches additional pages and objects. Keep the request volume appropriate to the diagnostic task.

Choose a diagnostic command ---------------------------

| Question | Command | What to inspect | | ------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------ | | Where does a handle point? | `fedify webfinger @alice@example.com` | The JSON resource descriptor's `subject`, `aliases`, and ActivityPub `self` link. | | Can the actor or object be fetched? | `fedify lookup @alice@example.com` | The parsed vocabulary object, its `id`, type, inbox, and advertised collection URLs. | | What software does the instance advertise? | `fedify nodeinfo example.com` | Software name/version, protocols, usage, and registration policy. |

WebFinger discovers a resource; it does not fetch the actor document. `lookup` resolves and dereferences the resource. NodeInfo describes an instance and does not establish that a particular actor or inbox works.

Investigate a lookup failure

1. Run `webfinger` for a handle and inspect the `self` link whose type is `application/activity+json` or `application/ld+json` with the ActivityStreams profile. A profile-page link is for browsers and may not be the actor's ID.

2. Run `lookup` on that `self` URL. If this works while the handle fails, focus on WebFinger discovery, redirects, and the advertised link.

3. Choose a JSON output format after a successful lookup:

~~~~ sh fedify lookup --raw https://example.com/users/alice fedify nodeinfo --raw example.com ~~~~

`lookup` normally prints a vocabulary object. Its `--raw` option serializes the parsed object back to JSON-LD. `--compact` and `--expand` select other JSON-LD forms. These three format options are mutually exclusive, and all require successful parsing. To investigate a parsing failure, request the resource directly with an ActivityPub `Accept` header:

~~~~ sh curl -i -H 'Accept: application/activity+json' https://example.com/users/alice ~~~~

Inspect the status, `Content-Type`, and response body. This unsigned request may receive a different response from a server that requires signed fetch.

4. Record the exact command, CLI version, exit status, and error. Check DNS/TLS, HTTP errors, redirects, and content negotiation as indicated by the evidence. Do not conclude from a single failed request that an account does not exist. Use `fedify --debug lookup <target>` when more detail is needed; redact private content and credentials before sharing logs.

For a server requiring signed requests, consider:

~~~~ sh fedify lookup --authorized-fetch @alice@example.com ~~~~

This creates a one-time key pair and a temporary public server through a tunnel so the remote server can fetch the signing key. It does not log in as the user's account or grant access to private posts. Explain the exposure before running it and use it only within the user's authorized task.

Do not enable `--allow-private-address` for arbitrary remote data. It permits fetching private or loopback addresses; reserve it for an explicitly intended local test. See <https://fedify.dev/cli.md> for signature options, timeouts, and other version-