atproto-devtool#

A multitool for the atproto developer ecosystem.

Installation#

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.

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:

atproto-devtool test labeler moderation.bsky.app

Resolve by DID:

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:

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.

test oauth client#

Runs a conformance suite against an atproto OAuth client, validating DPoP and scope conformance. The suite has up to four stages:

• Discovery: Metadata URL is reachable and returns valid JSON.
• Metadata: Client metadata conforms to OAuth 2.0 and DPoP requirements.
• JWKS: JSON Web Key Set is present, valid, and keys are properly signed.
• Interactive (optional): Fake AS server exercises the client's full auth flow including PAR, authorization, token exchange, and refresh-token rotation.

Test an atproto OAuth client

Usage: atproto-devtool test oauth client [OPTIONS] <TARGET> [COMMAND]

Arguments:
  <TARGET>
          The client's `client_id` URL, or a loopback form for development clients.

Options:
      --no-color
          Suppress ANSI color in rendered output

      --verbose
          Emit DEBUG-level tracing

  -h, --help
          Print help

Commands:
  interactive
          Run static checks plus an interactive flow against a fake authorization server

Static Mode (Default)#

Validates the client's metadata and JWKS without driving an interactive flow:

atproto-devtool test oauth client https://client.example.com/metadata.json

Interactive Mode#

Instantiates a fake atproto authorization server and exercises the client's OAuth flow (PAR, authorize, token exchange, scope grants, DPoP nonce rotation, refresh-token rotation):

# Same-host client (default)
atproto-devtool test oauth client interactive

# Remote client via tunnel
atproto-devtool test oauth client interactive --public-base-url https://tunnel.example.com

See Reachability Workflows for detailed setup instructions for remote clients.

Exit codes#

• 0 — all checks pass.
• 1 — one or more spec violations (DPoP, scope, conformance issues).
• 2 — network errors (unreachable metadata, JWKS, or AS endpoint) with no spec violations.

License#

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (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.