@fedify/cli 2.5.0-dev.2496 → 2.5.0-dev.2504
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/deno.js +1 -1
- package/package.json +20 -11
- package/skills/fedify-cli/SKILL.md +274 -0
package/dist/deno.js
CHANGED
package/package.json
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fedify/cli",
|
|
3
|
-
"version": "2.5.0-dev.
|
|
3
|
+
"version": "2.5.0-dev.2504+fdeb138d",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"files": [
|
|
6
6
|
"README.md",
|
|
7
|
-
"dist/"
|
|
7
|
+
"dist/",
|
|
8
|
+
"skills/"
|
|
8
9
|
],
|
|
9
10
|
"bin": {
|
|
10
11
|
"fedify": "./dist/mod.js"
|
|
@@ -88,14 +89,14 @@
|
|
|
88
89
|
"temporal-polyfill": "^1.0.1",
|
|
89
90
|
"valibot": "^1.4.0",
|
|
90
91
|
"yaml": "^2.9.0",
|
|
91
|
-
"@fedify/init": "2.5.0-dev.
|
|
92
|
-
"@fedify/fedify": "2.5.0-dev.
|
|
93
|
-
"@fedify/
|
|
94
|
-
"@fedify/
|
|
95
|
-
"@fedify/
|
|
96
|
-
"@fedify/vocab-
|
|
97
|
-
"@fedify/webfinger": "2.5.0-dev.
|
|
98
|
-
"@fedify/vocab": "2.5.0-dev.
|
|
92
|
+
"@fedify/init": "2.5.0-dev.2504+fdeb138d",
|
|
93
|
+
"@fedify/fedify": "2.5.0-dev.2504+fdeb138d",
|
|
94
|
+
"@fedify/sqlite": "2.5.0-dev.2504+fdeb138d",
|
|
95
|
+
"@fedify/vocab": "2.5.0-dev.2504+fdeb138d",
|
|
96
|
+
"@fedify/relay": "2.5.0-dev.2504+fdeb138d",
|
|
97
|
+
"@fedify/vocab-runtime": "2.5.0-dev.2504+fdeb138d",
|
|
98
|
+
"@fedify/webfinger": "2.5.0-dev.2504+fdeb138d",
|
|
99
|
+
"@fedify/vocab-tools": "2.5.0-dev.2504+fdeb138d"
|
|
99
100
|
},
|
|
100
101
|
"devDependencies": {
|
|
101
102
|
"@types/bun": "^1.2.23",
|
|
@@ -105,12 +106,20 @@
|
|
|
105
106
|
"typescript": "^6.0.0",
|
|
106
107
|
"@fedify/fixture": "2.0.0"
|
|
107
108
|
},
|
|
109
|
+
"agents": {
|
|
110
|
+
"skills": [
|
|
111
|
+
{
|
|
112
|
+
"name": "fedify-cli",
|
|
113
|
+
"path": "./skills/fedify-cli"
|
|
114
|
+
}
|
|
115
|
+
]
|
|
116
|
+
},
|
|
108
117
|
"scripts": {
|
|
109
118
|
"build:self": "tsdown",
|
|
110
119
|
"build": "pnpm --filter @fedify/cli... run build:self",
|
|
111
120
|
"prepublish": "pnpm build",
|
|
112
121
|
"pretest": "pnpm build",
|
|
113
|
-
"test": "node --test --experimental-transform-types 'src/**/*.test.ts' '!src/init/test/**'",
|
|
122
|
+
"test": "node --test --experimental-transform-types 'src/**/*.test.ts' '!src/init/test/**' scripts/pack-skills.test.mjs",
|
|
114
123
|
"test-init": "deno task test-init",
|
|
115
124
|
"pretest:bun": "pnpm build",
|
|
116
125
|
"test:bun": "bun test --timeout 60000",
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: fedify-cli
|
|
3
|
+
description: >-
|
|
4
|
+
Use the fedify CLI to inspect and debug ActivityPub servers, including
|
|
5
|
+
servers built without the Fedify framework. Apply when looking up actors
|
|
6
|
+
or objects, diagnosing handle discovery or federation failures, fetching
|
|
7
|
+
WebFinger or NodeInfo, traversing collections or reply chains, resolving
|
|
8
|
+
portable objects through gateways, testing delivery with an
|
|
9
|
+
ephemeral inbox, exposing a local server through a tunnel, running a test
|
|
10
|
+
relay, or scaffolding a project with fedify init. Covers installation,
|
|
11
|
+
version checks, command selection, output interpretation, and remote
|
|
12
|
+
effects. Use for fedify CLI tasks even outside a JavaScript project.
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
Fedify CLI skill
|
|
16
|
+
================
|
|
17
|
+
|
|
18
|
+
Use `fedify` to inspect ActivityPub servers without writing an application.
|
|
19
|
+
The target server can use any framework. For building an application with
|
|
20
|
+
Fedify's TypeScript APIs, use the separate `fedify` skill.
|
|
21
|
+
|
|
22
|
+
Read <https://fedify.dev/cli.md> for detailed options. The documentation is
|
|
23
|
+
available as raw Markdown with the `.md` suffix; remove that suffix when
|
|
24
|
+
presenting links to the user. These examples target Fedify CLI 2.5.0.
|
|
25
|
+
If the installed version differs, its `--help` output takes precedence over
|
|
26
|
+
these examples.
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
Check the command first
|
|
30
|
+
-----------------------
|
|
31
|
+
|
|
32
|
+
~~~~ sh
|
|
33
|
+
fedify --version
|
|
34
|
+
fedify --help
|
|
35
|
+
fedify lookup --help
|
|
36
|
+
~~~~
|
|
37
|
+
|
|
38
|
+
Check the chosen subcommand's `--help` before using version-dependent flags.
|
|
39
|
+
Use a project-local executable when the project already provides one. In a
|
|
40
|
+
Fedify source checkout, follow its contributor instructions and use
|
|
41
|
+
`mise run cli -- <arguments>`.
|
|
42
|
+
|
|
43
|
+
If the command is missing, choose an installation method that fits the user's
|
|
44
|
+
runtime. For example, with Node.js:
|
|
45
|
+
|
|
46
|
+
~~~~ sh
|
|
47
|
+
npm install -g @fedify/cli
|
|
48
|
+
~~~~
|
|
49
|
+
|
|
50
|
+
Deno, Bun, Homebrew, Scoop, mise, and standalone executables are covered at
|
|
51
|
+
<https://fedify.dev/cli.md#installation>. Installing the CLI executable and
|
|
52
|
+
installing this skill are separate steps; see
|
|
53
|
+
<https://fedify.dev/install.md#agentic-skill>.
|
|
54
|
+
|
|
55
|
+
Configuration files can supply defaults, including options that contact
|
|
56
|
+
remote servers. Inspect relevant defaults before running diagnostics. For
|
|
57
|
+
an isolated invocation, put `--ignore-config` before the subcommand:
|
|
58
|
+
|
|
59
|
+
~~~~ sh
|
|
60
|
+
fedify --ignore-config lookup @alice@example.com
|
|
61
|
+
~~~~
|
|
62
|
+
|
|
63
|
+
The domains and handles below are placeholders. Substitute the user's target.
|
|
64
|
+
Discovery and lookup commands contact remote servers and may appear in their
|
|
65
|
+
logs. Traversal fetches additional pages and objects. Keep the request volume
|
|
66
|
+
appropriate to the diagnostic task.
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
Choose a diagnostic command
|
|
70
|
+
---------------------------
|
|
71
|
+
|
|
72
|
+
| Question | Command | What to inspect |
|
|
73
|
+
| ------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
74
|
+
| Where does a handle point? | `fedify webfinger @alice@example.com` | The JSON resource descriptor's `subject`, `aliases`, and ActivityPub `self` link. |
|
|
75
|
+
| Can the actor or object be fetched? | `fedify lookup @alice@example.com` | The parsed vocabulary object, its `id`, type, inbox, and advertised collection URLs. |
|
|
76
|
+
| What software does the instance advertise? | `fedify nodeinfo example.com` | Software name/version, protocols, usage, and registration policy. |
|
|
77
|
+
|
|
78
|
+
WebFinger discovers a resource; it does not fetch the actor document.
|
|
79
|
+
`lookup` resolves and dereferences the resource. NodeInfo describes an
|
|
80
|
+
instance and does not establish that a particular actor or inbox works.
|
|
81
|
+
|
|
82
|
+
### Investigate a lookup failure
|
|
83
|
+
|
|
84
|
+
1. Run `webfinger` for a handle and inspect the `self` link whose type is
|
|
85
|
+
`application/activity+json` or `application/ld+json` with the
|
|
86
|
+
ActivityStreams profile. A profile-page link is for browsers and may not be
|
|
87
|
+
the actor's ID.
|
|
88
|
+
|
|
89
|
+
2. Run `lookup` on that `self` URL. If this works while the handle fails,
|
|
90
|
+
focus on WebFinger discovery, redirects, and the advertised link.
|
|
91
|
+
|
|
92
|
+
3. Choose a JSON output format after a successful lookup:
|
|
93
|
+
|
|
94
|
+
~~~~ sh
|
|
95
|
+
fedify lookup --raw https://example.com/users/alice
|
|
96
|
+
fedify nodeinfo --raw example.com
|
|
97
|
+
~~~~
|
|
98
|
+
|
|
99
|
+
`lookup` normally prints a vocabulary object. Its `--raw` option
|
|
100
|
+
serializes the parsed object back to JSON-LD. `--compact` and `--expand`
|
|
101
|
+
select other JSON-LD forms. These three format options are mutually
|
|
102
|
+
exclusive, and all require successful parsing. To investigate a parsing
|
|
103
|
+
failure, request the resource directly with an ActivityPub `Accept`
|
|
104
|
+
header:
|
|
105
|
+
|
|
106
|
+
~~~~ sh
|
|
107
|
+
curl -i -H 'Accept: application/activity+json' https://example.com/users/alice
|
|
108
|
+
~~~~
|
|
109
|
+
|
|
110
|
+
Inspect the status, `Content-Type`, and response body. This unsigned
|
|
111
|
+
request may receive a different response from a server that requires
|
|
112
|
+
signed fetch.
|
|
113
|
+
|
|
114
|
+
4. Record the exact command, CLI version, exit status, and error. Check
|
|
115
|
+
DNS/TLS, HTTP errors, redirects, and content negotiation as indicated by
|
|
116
|
+
the evidence. Do not conclude from a single failed request that an account
|
|
117
|
+
does not exist. Use `fedify --debug lookup <target>` when more detail is
|
|
118
|
+
needed; redact private content and credentials before sharing logs.
|
|
119
|
+
|
|
120
|
+
For a server requiring signed requests, consider:
|
|
121
|
+
|
|
122
|
+
~~~~ sh
|
|
123
|
+
fedify lookup --authorized-fetch @alice@example.com
|
|
124
|
+
~~~~
|
|
125
|
+
|
|
126
|
+
This creates a one-time key pair and a temporary public server through a
|
|
127
|
+
tunnel so the remote server can fetch the signing key. It does not log in as
|
|
128
|
+
the user's account or grant access to private posts. Explain the exposure
|
|
129
|
+
before running it and use it only within the user's authorized task.
|
|
130
|
+
|
|
131
|
+
Do not enable `--allow-private-address` for arbitrary remote data. It permits
|
|
132
|
+
fetching private or loopback addresses; reserve it for an explicitly intended
|
|
133
|
+
local test. See <https://fedify.dev/cli.md> for signature options, timeouts,
|
|
134
|
+
and other version-specific diagnostics.
|
|
135
|
+
|
|
136
|
+
### Traverse a collection
|
|
137
|
+
|
|
138
|
+
Copy the collection URL from the fetched actor, then inspect it before
|
|
139
|
+
traversing it:
|
|
140
|
+
|
|
141
|
+
~~~~ sh
|
|
142
|
+
fedify lookup https://example.com/users/alice/outbox
|
|
143
|
+
fedify lookup --traverse https://example.com/users/alice/outbox
|
|
144
|
+
~~~~
|
|
145
|
+
|
|
146
|
+
Without `--traverse`, the result is the collection itself. With it, the
|
|
147
|
+
command follows collection pages and prints their items. Each target must
|
|
148
|
+
resolve to a collection, so passing the actor URL is insufficient. Separate
|
|
149
|
+
results use `----` by default; do not treat the entire stream as one JSON
|
|
150
|
+
array. Traversal can fetch many pages and objects. Keep errors visible while
|
|
151
|
+
diagnosing; `--suppress-errors` can produce partial results and does not prove
|
|
152
|
+
every item was retrieved. Use the CLI reference for separators, output files,
|
|
153
|
+
and relationship recursion rather than guessing flags.
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
Advanced diagnostic recipes
|
|
157
|
+
---------------------------
|
|
158
|
+
|
|
159
|
+
### Reconstruct a conversation from one post
|
|
160
|
+
|
|
161
|
+
Follow a post's reply targets to inspect its ancestors without relying on a
|
|
162
|
+
server's web UI:
|
|
163
|
+
|
|
164
|
+
~~~~ sh
|
|
165
|
+
fedify lookup --recurse replyTarget --recurse-depth 5 --reverse https://example.com/posts/leaf
|
|
166
|
+
fedify lookup --recurse quote --recurse-depth 3 https://example.com/posts/quoted
|
|
167
|
+
~~~~
|
|
168
|
+
|
|
169
|
+
`replyTarget` is the vocabulary property name for ActivityStreams
|
|
170
|
+
`inReplyTo`. `quote` and `quoteUrl` follow quote relationships instead. A
|
|
171
|
+
depth limit bounds the walk; it does not establish that the conversation is
|
|
172
|
+
complete. `--reverse` buffers results before printing them in reverse order,
|
|
173
|
+
which can make an ancestor chain easier to read. Relationship recursion and
|
|
174
|
+
`--traverse` are mutually exclusive: use recursion for links between objects
|
|
175
|
+
and traversal for collection membership. This can help locate a broken link
|
|
176
|
+
or a serialization difference between servers.
|
|
177
|
+
|
|
178
|
+
### Compare discovery before and after an account move
|
|
179
|
+
|
|
180
|
+
Use multiple targets to inspect both handles in one terminal session:
|
|
181
|
+
|
|
182
|
+
~~~~ sh
|
|
183
|
+
fedify webfinger @alice@old.example @alice@new.example
|
|
184
|
+
fedify lookup --raw @alice@old.example @alice@new.example
|
|
185
|
+
~~~~
|
|
186
|
+
|
|
187
|
+
Compare WebFinger `self` links, actor IDs, and any advertised `movedTo` or
|
|
188
|
+
`alsoKnownAs` relationships. A matching display name is not evidence that two
|
|
189
|
+
actors are the same identity. This is an inspection workflow; it does not
|
|
190
|
+
move accounts or send a `Move` activity. For a reproducible diagnostic
|
|
191
|
+
artifact, `lookup --raw --output actor.json <actor-url>` saves the parsed
|
|
192
|
+
actor as JSON-LD. Review private content before sharing it, and remember that a
|
|
193
|
+
multi-target output uses separators rather than forming a JSON array.
|
|
194
|
+
|
|
195
|
+
### Separate portable identity from gateway availability
|
|
196
|
+
|
|
197
|
+
On versions supporting FEP-ef61 portable objects, provide a gateway for a
|
|
198
|
+
bare portable ID:
|
|
199
|
+
|
|
200
|
+
~~~~ sh
|
|
201
|
+
fedify lookup --gateway https://gateway.example 'ap://did:key:z6Mk.../actor'
|
|
202
|
+
~~~~
|
|
203
|
+
|
|
204
|
+
Replace the abbreviated DID and path with the complete ID under test.
|
|
205
|
+
Portable IDs carry identity independently of the serving host. A gateway URL
|
|
206
|
+
or an ID with `@gateway` location hints can supply the fetch location instead
|
|
207
|
+
of `--gateway`. Distinguish a gateway fetch failure from an integrity-proof
|
|
208
|
+
failure: successfully receiving JSON does not mean its proof is valid.
|
|
209
|
+
The CLI validates the portable object's integrity proof before accepting it.
|
|
210
|
+
See <https://fedify.dev/cli.md#looking-up-portable-objects> for identifier
|
|
211
|
+
forms and gateway rules.
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
Create a project
|
|
215
|
+
----------------
|
|
216
|
+
|
|
217
|
+
~~~~ sh
|
|
218
|
+
fedify init my-federated-app
|
|
219
|
+
~~~~
|
|
220
|
+
|
|
221
|
+
`init` runs an interactive wizard for runtime, package manager, framework,
|
|
222
|
+
KV store, and message queue. Choose an intended new directory and resolve
|
|
223
|
+
those choices with the user before running the wizard. Scaffolding writes
|
|
224
|
+
files and may install dependencies. It is useful for a new Fedify app, but is
|
|
225
|
+
not needed for CLI-only diagnosis. See
|
|
226
|
+
<https://fedify.dev/cli.md#fedify-init-initializing-a-fedify-project>.
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
Receive test activities
|
|
230
|
+
-----------------------
|
|
231
|
+
|
|
232
|
+
~~~~ sh
|
|
233
|
+
fedify inbox
|
|
234
|
+
~~~~
|
|
235
|
+
|
|
236
|
+
This starts a temporary actor and inbox with a public HTTPS tunnel. Use the
|
|
237
|
+
printed actor handle or URI as a recipient from the server under test, then
|
|
238
|
+
inspect the logged activity type, HTTP status, and request-details URL. A
|
|
239
|
+
successful HTTP response alone does not establish that an application's
|
|
240
|
+
business logic handled an activity. Stop the process with Ctrl-C when done;
|
|
241
|
+
the actor and tunnel are short-lived.
|
|
242
|
+
|
|
243
|
+
For a local-only test, check `fedify inbox --help` for `--no-tunnel`. Remote
|
|
244
|
+
peers cannot reach a loopback-only endpoint.
|
|
245
|
+
|
|
246
|
+
`--follow` sends Follow activities to the named actors, and `--accept-follow`
|
|
247
|
+
can send Accept activities. These affect remote servers; use them only when
|
|
248
|
+
the user has authorized that interaction. Inspect configuration defaults so
|
|
249
|
+
a plain `inbox` invocation does not unexpectedly follow or accept actors.
|
|
250
|
+
See <https://fedify.dev/cli.md#fedify-inbox-ephemeral-inbox-server>.
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
Expose a local server or test a relay
|
|
254
|
+
-------------------------------------
|
|
255
|
+
|
|
256
|
+
~~~~ sh
|
|
257
|
+
fedify tunnel 3000
|
|
258
|
+
fedify relay --protocol mastodon
|
|
259
|
+
~~~~
|
|
260
|
+
|
|
261
|
+
`tunnel` exposes an existing local HTTP service to the public internet. Use
|
|
262
|
+
it only for the intended development service, with test data. Ensure that
|
|
263
|
+
the service recognizes its public origin, including forwarded headers where
|
|
264
|
+
appropriate, so actor IDs do not point to localhost.
|
|
265
|
+
|
|
266
|
+
`relay` runs an ActivityPub relay and forwards activities between participating
|
|
267
|
+
servers. It opens a public tunnel by default and uses in-memory storage
|
|
268
|
+
unless persistence is configured. Choose Mastodon or LitePub according to
|
|
269
|
+
the test, and use controlled participants; accepting subscriptions and
|
|
270
|
+
forwarding activities have remote effects. Starting a relay is not a passive
|
|
271
|
+
connectivity check. Stop temporary servers when the test ends.
|
|
272
|
+
|
|
273
|
+
Read <https://fedify.dev/cli.md> for tunnel providers, relay persistence,
|
|
274
|
+
subscription controls, and local-only modes.
|