pdsx 0.0.1a1

general-purpose cli for atproto record operations

pdsx

general-purpose cli for atproto record operations

installation

uv add pdsx
# or
uvx pdsx --help

quick start

set your credentials:

export ATPROTO_HANDLE=your.handle
export ATPROTO_PASSWORD=your-password

list posts (compact format by default):

pdsx ls app.bsky.feed.post --limit 10

json output for jq:

pdsx ls app.bsky.feed.post -o json | jq '.[].text'

table view:

pdsx ls app.bsky.feed.post -o table

features

• crud operations for atproto records (list, get, create, update, delete)
• multiple output formats: compact (default), json, yaml, table
• unix-style command aliases: ls, cat, rm, edit, touch/add
• clean json output for jq/pipe interoperability
• tty-aware formatting
• type-safe with strict typing
• python 3.10+ support

usage

list records

# using full command
pdsx list app.bsky.feed.post --limit 5

# using alias
pdsx ls app.bsky.feed.post --limit 5 -o json

get a record

# using full command
pdsx get at://did:plc:example/app.bsky.feed.post/123

# using alias
pdsx cat at://did:plc:example/app.bsky.feed.post/123

create a record

pdsx create app.bsky.feed.like subject='at://...' createdAt='2024-01-01T00:00:00Z'

# using alias
pdsx touch app.bsky.feed.like subject='at://...' createdAt='2024-01-01T00:00:00Z'

update a record

pdsx update at://did:plc:example/app.bsky.feed.post/123 text='updated text'

# using alias
pdsx edit at://did:plc:example/app.bsky.feed.post/123 text='updated text'

delete a record

pdsx delete at://did:plc:example/app.bsky.feed.post/123

# using alias
pdsx rm at://did:plc:example/app.bsky.feed.post/123

output formats

compact (default)

one line per record with json:

app.bsky.feed.post (3 records)
3m4ryxwq5dt2i: {"created_at":"2025-11-04T07:25:17.061883+00:00","text":"..."}
3m4ryxvw4l32z: {"created_at":"2025-11-04T07:25:16.201083+00:00","text":"..."}

json

clean json for piping to jq:

pdsx ls app.bsky.feed.post -o json | jq '.[].text'

table

pretty table for terminal viewing:

pdsx ls app.bsky.feed.post -o table

examples

click to see real-world examples

read anyone's bio

uvx pdsx --repo did:plc:o53crari67ge7bvbv273lxln list app.bsky.actor.profile -o json | \
  jq -r '.[0].description'

update your bio

export ATPROTO_HANDLE=your.handle ATPROTO_PASSWORD=your-password
uvx pdsx edit app.bsky.actor.profile/self description='new bio'

read anyone's posts

uvx pdsx -r did:plc:o53crari67ge7bvbv273lxln list app.bsky.feed.post --limit 5 -o json | \
  jq -r '.[] | .text'

atproto gives you full read access to anyone's public data. auth only required for writes.

development

# clone repo
git clone https://github.com/zzstoatzz/pdsx
cd pdsx

# install with dev dependencies
uv sync

# run tests
uv run pytest

# run type checker
uv run ty check

# run pre-commit hooks
uv run prek run --all-files

license

mit