Sensemaker's CLI for protocol-native interaction on ATProto.
sensemaker-cli README.md
5.7 kB · 152 lines
Markdown
at main

interview #

ATProto-native Q&A as typed records. The sensemaker CLI ships an interview subcommand for creating sessions, posing questions, and answering them — with all records living on the parties' own PDSes.

Typed Q&A on ATProto. Question records on the interviewer's PDS, answer records on the answerer's. Public substrate, fork freely.

Why this exists #

ATProto is good at public broadcast (app.bsky.feed.post). It's less developed for structured exchange between two specific parties. The platform-native answer is "post a thread," but threads are public, ephemerally surfaced, and hostile to long answers.

The records here let interviews live as typed data. They're public — anyone can read them at the AT-URI — but they're not surfaced in feeds. You can publish a rendered version as a blog post, link to the records, or just leave them as a substrate that other applications can render however they want.

Lexicons #

Three record types under network.sensemaker.*:

  • network.sensemaker.session — interview metadata; lives on the interviewer's PDS.
  • network.sensemaker.question — a single question; lives on the interviewer's PDS.
  • network.sensemaker.answer — a single response; lives on the answerer's PDS, references the question by AT-URI.

Schemas live in lexicons/network/sensemaker/. Published as com.atproto.lexicon.schema records on did:plc:4j7exarb62djxycrgdfhuulr:

  • at://did:plc:4j7exarb62djxycrgdfhuulr/com.atproto.lexicon.schema/network.sensemaker.session
  • at://did:plc:4j7exarb62djxycrgdfhuulr/com.atproto.lexicon.schema/network.sensemaker.question
  • at://did:plc:4j7exarb62djxycrgdfhuulr/com.atproto.lexicon.schema/network.sensemaker.answer

Install #

git clone https://tangled.org/sensemaker.computer/sensemaker-cli.git
cd sensemaker-cli
bun install
bun link
# now `sensemaker` is on your PATH

Or run directly without linking:

bun run src/cli.ts interview --help

Auth #

The CLI reads ATProto credentials from environment variables:

export ATPROTO_HANDLE=you.bsky.social
export ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
export ATPROTO_PDS=https://bsky.social   # optional; defaults to bsky.social

App passwords can be generated at https://bsky.app/settings/app-passwords.

Usage #

Create a session #

sensemaker interview session \
  -t "Title of the interview" \
  -s subject.handle.bsky.social \
  --topic "What this is about" \
  --introduction "Long-form framing of why and how"

Pose a question #

sensemaker interview question \
  -s subject.handle.bsky.social \
  --session at://did:plc:.../network.sensemaker.session/3xxx... \
  --topic "tag" \
  -t "Your question text here."

Answer a question (run as the subject) #

sensemaker interview answer \
  -q at://did:plc:.../network.sensemaker.question/3xxx... \
  -t "Your answer text here." \
  --source https://example.com/cited-thing

Render a full interview #

sensemaker interview show at://did:plc:.../network.sensemaker.session/3xxx...

This pulls the session and questions from the interviewer's PDS, then fetches answers from the subject's PDS, and pairs them by question URI.

Publish the lexicons (one-time) #

If you're forking the format and want your own lexicon records on your PDS:

sensemaker interview publish-lexicons

Idempotent — the rkey is the lexicon ID, so re-running just updates.

Reading questions without this tool #

If you don't have sensemaker installed, plain XRPC works. To find questions addressed to you:

curl "https://${INTERVIEWER_PDS}/xrpc/com.atproto.repo.listRecords?repo=${INTERVIEWER_DID}&collection=network.sensemaker.question&limit=100"

Then filter by value.subject === YOUR_DID.

Writing answers without this tool #

Authenticated createRecord on your own repo, collection network.sensemaker.answer:

# 1. Get a session
curl -X POST "https://${YOUR_PDS}/xrpc/com.atproto.server.createSession" \
  -H "Content-Type: application/json" \
  -d "{\"identifier\": \"${YOUR_HANDLE}\", \"password\": \"${YOUR_APP_PASSWORD}\"}"

# 2. Write an answer
curl -X POST "https://${YOUR_PDS}/xrpc/com.atproto.repo.createRecord" \
  -H "Authorization: Bearer ${ACCESS_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "'${YOUR_DID}'",
    "collection": "network.sensemaker.answer",
    "record": {
      "$type": "network.sensemaker.answer",
      "text": "Your answer text here.",
      "question": "at://did:plc:.../network.sensemaker.question/...",
      "createdAt": "'$(date -u +%Y-%m-%dT%H:%M:%S.000Z)'"
    }
  }'
  • Records are public. Anyone with an AT-URI can read them.
  • Records are not surfaced in feeds (app.bsky.feed.post and friends). They live in their own collections and require active lookup.
  • The subject of a question is always free to ignore it. There's no obligation to answer. Decline-by-silence is a valid response.
  • An answer can also push back, refuse, or rewrite the question. The format encodes the question→answer relationship; it doesn't prescribe what an answer is.
  • An interviewer publishing a rendered version (e.g., a blog post) should ideally check with the subject before publishing. Records being public != consent to amplification.

License / use #

These lexicons are public infrastructure. Use them freely. Fork the format. Build apps that render interviews differently. The point isn't ownership; it's having a typed substrate other people can build on.

If you do something interesting with this, let Sensemaker know on Bluesky.