# atproto-devtool

A multitool for the [atproto](https://atproto.com/) developer ecosystem.

## Installation

| Environment | CLI command |
|-------------|-------------|
| Cargo (Rust 1.85+) | `cargo install atproto-devtool` |

## Usage

### `test labeler`

Runs a conformance suite against a labeler, and produces a structured report
with per-check results plus a summary exit code. The suite has four stages:

- **Identity**: DID document contains the correct entries, and the labeler's PDS
  holds a valid labeler record.
- **HTTP**: Checks the `com.atproto.label.queryLabels` XRPC API.
- **Subscription**: Checks the `com.atproto.label.subscribeLabels` WebSocket.
- **Crypto**: Samples labels and verifies their signatures.

```text
Run the labeler conformance suite against an atproto labeler

Usage: atproto-devtool test labeler [OPTIONS] <TARGET>

Arguments:
  <TARGET>
          Handle (`alice.example`), DID (`did:plc:...` / `did:web:...`), or labeler endpoint URL

Options:
      --did <DID>
          Explicit DID override. Required (and combined with the target URL) when `target` is a raw
          endpoint URL and you want identity/crypto checks to run

      --subscribe-timeout <SUBSCRIBE_TIMEOUT>
          Per-connection time budget for the subscription-layer checks.

          Minimum 1 second; values below 1 second are rejected at parse time.

          [default: 5s]

      --no-color
          Whether to suppress colored output

      --verbose
          Whether to emit verbose diagnostics

  -h, --help
          Print help (see a summary with '-h')
```

#### Examples

Resolve by handle:

```bash
atproto-devtool test labeler moderation.bsky.app
```

Resolve by DID:

```bash
atproto-devtool test labeler did:plc:ar7c4by46qjdydhdevvrndac
```

Point at a raw labeler endpoint and supply the DID separately so identity and
crypto stages still run:

```bash
atproto-devtool test labeler https://mod.bsky.app --did did:plc:ar7c4by46qjdydhdevvrndac
```

Pass `--verbose` to any of the above to emit `DEBUG`-level tracing on stderr
(HTTP requests, WebSocket connect/disconnect and frame counts, PLC audit-log
fetches, per-label verification). `NO_COLOR=1` or `--no-color` disables ANSI
escape sequences in the rendered report.

#### Exit codes

- `0` — all spec-required checks passed (advisories and skipped checks are
  allowed).
- `1` — one or more spec-required checks failed.
- `2` — no spec-required checks failed but one or more network errors occurred.

## License

Licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
   http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or
conditions.
