CLI app for developers prototyping atproto functionality
1# atproto-devtool
2
3A multitool for the [atproto](https://atproto.com/) developer ecosystem.
4
5## Installation
6
7| Environment | CLI command |
8|-------------|-------------|
9| Cargo (Rust 1.85+) | `cargo install atproto-devtool` |
10
11## Usage
12
13### `test labeler`
14
15Runs a conformance suite against a labeler, and produces a structured report
16with per-check results plus a summary exit code. The suite has four stages:
17
18- **Identity**: DID document contains the correct entries, and the labeler's PDS
19 holds a valid labeler record.
20- **HTTP**: Checks the `com.atproto.label.queryLabels` XRPC API.
21- **Subscription**: Checks the `com.atproto.label.subscribeLabels` WebSocket.
22- **Crypto**: Samples labels and verifies their signatures.
23
24```text
25Run the labeler conformance suite against an atproto labeler
26
27Usage: atproto-devtool test labeler [OPTIONS] <TARGET>
28
29Arguments:
30 <TARGET>
31 Handle (`alice.example`), DID (`did:plc:...` / `did:web:...`), or labeler endpoint URL
32
33Options:
34 --did <DID>
35 Explicit DID override. Required (and combined with the target URL) when `target` is a raw
36 endpoint URL and you want identity/crypto checks to run
37
38 --subscribe-timeout <SUBSCRIBE_TIMEOUT>
39 Per-connection time budget for the subscription-layer checks.
40
41 Minimum 1 second; values below 1 second are rejected at parse time.
42
43 [default: 5s]
44
45 --no-color
46 Whether to suppress colored output
47
48 --verbose
49 Whether to emit verbose diagnostics
50
51 -h, --help
52 Print help (see a summary with '-h')
53```
54
55#### Examples
56
57Resolve by handle:
58
59```bash
60atproto-devtool test labeler moderation.bsky.app
61```
62
63Resolve by DID:
64
65```bash
66atproto-devtool test labeler did:plc:ar7c4by46qjdydhdevvrndac
67```
68
69Point at a raw labeler endpoint and supply the DID separately so identity and
70crypto stages still run:
71
72```bash
73atproto-devtool test labeler https://mod.bsky.app --did did:plc:ar7c4by46qjdydhdevvrndac
74```
75
76Pass `--verbose` to any of the above to emit `DEBUG`-level tracing on stderr
77(HTTP requests, WebSocket connect/disconnect and frame counts, PLC audit-log
78fetches, per-label verification). `NO_COLOR=1` or `--no-color` disables ANSI
79escape sequences in the rendered report.
80
81#### Exit codes
82
83- `0` — all spec-required checks passed (advisories and skipped checks are
84 allowed).
85- `1` — one or more spec-required checks failed.
86- `2` — no spec-required checks failed but one or more network errors occurred.
87
88### `test oauth client`
89
90Runs a conformance suite against an atproto OAuth client, validating DPoP and
91scope conformance. The suite has up to four stages:
92
93- **Discovery**: Metadata URL is reachable and returns valid JSON.
94- **Metadata**: Client metadata conforms to OAuth 2.0 and DPoP requirements.
95- **JWKS**: JSON Web Key Set is present, valid, and keys are properly signed.
96- **Interactive** (optional): Fake AS server exercises the client's full auth
97 flow including PAR, authorization, token exchange, and refresh-token rotation.
98
99```text
100Test an atproto OAuth client
101
102Usage: atproto-devtool test oauth client [OPTIONS] <TARGET> [COMMAND]
103
104Arguments:
105 <TARGET>
106 The client's `client_id` URL, or a loopback form for development clients.
107
108Options:
109 --no-color
110 Suppress ANSI color in rendered output
111
112 --verbose
113 Emit DEBUG-level tracing
114
115 -h, --help
116 Print help
117
118Commands:
119 interactive
120 Run static checks plus an interactive flow against a fake authorization server
121```
122
123#### Static Mode (Default)
124
125Validates the client's metadata and JWKS without driving an interactive flow:
126
127```bash
128atproto-devtool test oauth client https://client.example.com/metadata.json
129```
130
131#### Interactive Mode
132
133Instantiates a fake atproto authorization server and exercises the client's
134OAuth flow (PAR, authorize, token exchange, scope grants, DPoP nonce rotation,
135refresh-token rotation):
136
137```bash
138# Same-host client (default)
139atproto-devtool test oauth client interactive
140
141# Remote client via tunnel
142atproto-devtool test oauth client interactive --public-base-url https://tunnel.example.com
143```
144
145See [Reachability Workflows](docs/test-oauth-client-reachability.md) for
146detailed setup instructions for remote clients.
147
148#### Exit codes
149
150- `0` — all checks pass.
151- `1` — one or more spec violations (DPoP, scope, conformance issues).
152- `2` — network errors (unreachable metadata, JWKS, or AS endpoint) with no
153 spec violations.
154
155## License
156
157Licensed under either of
158
159 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
160 http://www.apache.org/licenses/LICENSE-2.0)
161 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
162
163at your option.
164
165### Contribution
166
167Unless you explicitly state otherwise, any contribution intentionally
168submitted for inclusion in the work by you, as defined in the Apache-2.0
169license, shall be dual licensed as above, without any additional terms or
170conditions.