atp — ATProto record inspector

An interactive terminal app for debugging ATProto / Bluesky repositories. Give it a handle or DID and browse the identity, its collections, and every record — with syntax-highlighted JSON, live search, and blob inspection. Built with Ink (React for the terminal), the same stack Claude Code's CLI uses.

Read-only and unauthenticated: it inspects public repo data only. No login, no writes.

Install

Run it without installing anything (once published to npm):

npx atproto-inspect srtfisher.bsky.social

Or install the atp command globally:

npm install -g atproto-inspect
atp srtfisher.bsky.social

From source

npm install
npm run build
npm link      # exposes the global `atp` command

Requires Node 20+.

Usage

atp srtfisher.bsky.social      # launch and browse
atp did:plc:xxxx               # a DID works too
atp                            # prompts for a handle

# Point at a specific PDS (bare host or full URL). With --pds, the PDS is
# queried directly and public identity resolution is skipped — so a self-hosted
# PDS + DID works even when the DID isn't in the public PLC directory:
atp did:plc:bvbng3pv43ugysgkvhhalfcw --pds pds.chicago-com.alley.dev

Navigation

Screens drill down like a nav stack: Identity → Collections → Records → Record → Blob.

| Key | Action | | ---------- | --------------------------------------- | | ↑ ↓ / j k | Move selection | | ↵ | Open / drill in | | esc / ←| Back | | / | Search & filter records (esc cancels) | | y | Copy record JSON to clipboard | | s | Save record JSON to a file | | b | Inspect blobs referenced by a record | | g / G | Jump to top / bottom of a record | | d | Toggle the DID document (identity screen)| | q | Quit |

Non-interactive (scripting)

atp <handle> --json                        # identity + collections as JSON
atp <handle> --dump app.bsky.feed.post     # all records of a collection as JSON
atp <handle> --pds https://my.pds          # override PDS discovery

How it works

1. Resolve identity — handle → DID (@atproto/identity), then DID document → PDS endpoint, with a bi-directional handle-verification check. When --pds is given, this step is skipped: the PDS is queried directly via describeRepo, which returns the DID, handle, and DID document authoritatively.
2. Describe repo — com.atproto.repo.describeRepo lists collections.
3. List / get records — listRecords (paginated, loaded incrementally so you can browse as it fetches) and getRecord.
4. Blobs — record values are scanned for blob refs; com.atproto.sync.getBlob fetches the bytes on demand.

Development

npm run dev        # tsup watch build
npm run typecheck  # tsc --noEmit
npm test           # vitest

Layout

src/
  atproto/   data layer — framework-free SDK wrapper (identity, repo, summaries)
  ui/        Ink components — nav stack, screens, shared widgets
  lib/       JSON highlighter, clipboard/file helpers
  cli.tsx    arg parsing + interactive/non-interactive entry
test/        vitest unit + render tests

The data layer has no React dependency and is unit-tested independently of the UI.

Releasing

Releases are tag-driven — bump the version and push the tag, and CI publishes to npm and cuts the GitHub release. See RELEASING.md.

License

MIT