Addressing

the addressing problem

to read or write a record, pdsx needs to know:

which repository contains it
which collection within that repository
which specific record (if applicable)

ATProto solves this with AT-URIs and DIDs.

AT-URI format

AT-URIs identify records using this structure:

at://AUTHORITY/COLLECTION/RKEY

example:

at://did:plc:44ybard66vv44zksje25o7dz/app.bsky.feed.post/3jwdwj2ctlk26
^--^ ^------------ authority --------^ ^--- collection ---^ ^-- rkey --^
scheme        (repository)

components:

scheme: always at://
authority: DID or handle identifying the repository
collection: NSID of the collection (optional)
rkey: record key within collection (optional)

authority: DID vs handle

using DIDs

at://did:plc:44ybard66vv44zksje25o7dz/app.bsky.feed.post/3jwdwj2ctlk26

DIDs are:

permanent: never change
decentralized: not controlled by any provider
portable: work even if user changes PDS
cryptographic: tied to signing keys

best for: durable references, long-term storage

using handles

at://zzstoatzz.io/app.bsky.feed.post/3jwdwj2ctlk26

handles are:

human-readable: easier to type/remember
changeable: user can update their handle
reassignable: if abandoned, someone else can claim it
DNS/HTTP-based: resolved via DNS or .well-known

best for: user-facing displays, temporary references critical limitation: if user changes handle, handle-based URIs break or point to wrong repository.

how pdsx resolves addresses

with -r flag (handle)

pdsx -r zzstoatzz.io ls app.bsky.feed.post

resolution flow:

resolve handle → DID
- try DNS: _atproto.zzstoatzz.io TXT record
- fallback to HTTPS: https://zzstoatzz.io/.well-known/atproto-did
resolve DID → PDS URL
- fetch DID document
- extract PDS endpoint
query PDS for records
return results

with -r flag (DID)

pdsx -r did:plc:44ybard66vv44zksje25o7dz ls app.bsky.feed.post

resolution flow:

skip handle resolution (already have DID)
resolve DID → PDS URL
query PDS
return results

without -r flag (authenticated)

pdsx ls app.bsky.feed.post

uses authenticated session:

already authenticated with PDS
session knows your DID
query your own repository
return results

shorthand URIs in pdsx

IMPORTANT: Shorthand URIs (collection/rkey) only work when you have an active authenticated session. Without authentication, you must use full AT-URIs (at://authority/collection/rkey). If you see an “invalid URI format” error, this is likely why.

when authenticated, pdsx supports shorthand:

full URI

pdsx get at://did:plc:your-did/app.bsky.feed.post/3jwdwj2ctlk26

shorthand (when authenticated)

pdsx get app.bsky.feed.post/3jwdwj2ctlk26

pdsx automatically:

uses your DID from session
constructs full URI
executes operation

this only works for your own repository - you’re authenticated to it.

did document structure

dids resolve to did documents that contain:

{
  "id": "did:plc:44ybard66vv44zksje25o7dz",
  "alsoKnownAs": ["at://zzstoatzz.io"],
  "verificationMethod": [
    {
      "id": "#atproto",
      "type": "Multikey",
      "controller": "did:plc:44ybard66vv44zksje25o7dz",
      "publicKeyMultibase": "..."
    }
  ],
  "service": [
    {
      "id": "#atproto_pds",
      "type": "AtprotoPersonalDataServer",
      "serviceEndpoint": "https://bsky.social"
    }
  ]
}

key fields pdsx uses:

service: which pds hosts this repository
alsoKnownAs: current handle (for verification)
verificationMethod: public keys (for cryptographic verification)

pds discovery

pdsx finds the pds hosting a repository:

resolve authority (handle or did) → did
fetch did document from plc directory
extract service entry with type AtprotoPersonalDataServer
use serviceEndpoint as pds url

example:

did:plc:44ybard66vv44zksje25o7dz
  → did document
  → service endpoint: https://bsky.social
  → pdsx connects to https://bsky.social

—pds flag

pdsx lets you override pds discovery:

pdsx --pds https://my-pds.example.com ls app.bsky.feed.post

useful for:

testing local pds
using non-standard pds
debugging

note: authentication must still be with that specific pds.

why this addressing model matters

portability

if user migrates pds:

update did document → new service endpoint
did-based uris still work
handle-based uris still work (if handle unchanged)
pdsx follows did document to find new pds

federation

different users on different pds instances:

alice@pds1.com has did:plc:alice
bob@pds2.com has did:plc:bob
pdsx can read both repositories
resolves each did → correct pds

handles as aliases

handles are just friendly names:

did is permanent identity
handle can change
handle can be reassigned
did document links them

authentication and addressing

reading public records

pdsx -r other-user.handle ls app.bsky.feed.post

no auth needed:

pdsx resolves handle → did → pds
queries pds as anonymous client
pds returns public records

writing to own repository

export ATPROTO_HANDLE=your.handle
export ATPROTO_PASSWORD=your-password
pdsx create app.bsky.feed.post text='hello'

auth flow:

pdsx creates session with pds (using credentials)
pds validates credentials
pds returns session token + your did
pdsx uses session for subsequent requests
pds ensures you’re writing to your own repository

cross-repository references

when creating a record that references another repository’s record:

pdsx create app.bsky.feed.like \
  subject='at://other-user.handle/app.bsky.feed.post/abc123'

pdsx:

doesn’t need auth to other-user’s repository
just includes their uri in your record
stores in your repository
reference points across repositories

uri validation

pdsx performs minimal uri validation: valid formats:

at://authority/collection/rkey      # full
at://authority/collection            # collection-level
at://authority                       # repository-level
collection/rkey                      # shorthand (if authenticated)

invalid formats:

at://authority/invalid nsid/rkey    # spaces not allowed
authority/collection/rkey            # missing scheme
at://authority/rkey                  # missing collection

why understanding addressing matters for pdsx

-r flag specifies repository: can be handle or did

pdsx -r zzstoatzz.io ls collection     # handle
pdsx -r did:plc:abc123 ls collection  # did

shorthand requires auth: only works for your own repository

pdsx get collection/rkey              # needs auth

full uris are more durable: use dids, not handles

# durable
at://did:plc:abc123/collection/rkey

# fragile (if handle changes)
at://user.handle/collection/rkey

pds is discovered automatically: unless overridden with —pds

from concept to command

these addressing concepts translate directly to pdsx usage: reading with handle:

pdsx -r zzstoatzz.io ls app.bsky.feed.post

pdsx resolves handle → DID → PDS → fetches records reading with DID (more durable):

pdsx -r did:plc:44ybard66vv44zksje25o7dz ls app.bsky.feed.post

pdsx finds PDS from DID document → fetches records shorthand (authenticated only):

pdsx get app.bsky.feed.post/3jwdwj2ctlk26
pdsx edit app.bsky.actor.profile/self description='new bio'

pdsx uses client.me.did from session to construct full URI

Getting Started

Guides

Concepts

the addressing problem

AT-URI format

authority: DID vs handle

using DIDs

using handles

how pdsx resolves addresses

with -r flag (handle)

with -r flag (DID)

without -r flag (authenticated)

shorthand URIs in pdsx

full URI

shorthand (when authenticated)

did document structure

pds discovery

—pds flag

why this addressing model matters

portability

federation

handles as aliases

authentication and addressing

reading public records

writing to own repository

cross-repository references

uri validation

why understanding addressing matters for pdsx

from concept to command

further reading

​the addressing problem

​AT-URI format

​authority: DID vs handle

​using DIDs

​using handles

​how pdsx resolves addresses

​with -r flag (handle)

​with -r flag (DID)

​without -r flag (authenticated)

​shorthand URIs in pdsx

​full URI

​shorthand (when authenticated)

​did document structure

​pds discovery

​—pds flag

​why this addressing model matters

​portability

​federation

​handles as aliases

​authentication and addressing

​reading public records

​writing to own repository

​cross-repository references

​uri validation

​why understanding addressing matters for pdsx

​from concept to command

​further reading

the addressing problem

AT-URI format

authority: DID vs handle

using DIDs

using handles

how pdsx resolves addresses

with -r flag (handle)

with -r flag (DID)

without -r flag (authenticated)

shorthand URIs in pdsx

full URI

shorthand (when authenticated)

did document structure

pds discovery

—pds flag

why this addressing model matters

portability

federation

handles as aliases

authentication and addressing

reading public records

writing to own repository

cross-repository references

uri validation

why understanding addressing matters for pdsx

from concept to command

further reading