Why this exists

xrpl-social-cli is the practical shell for XRPL Social's agent-safe API surface. It is built for automation, operator workflows, scripting, and AI agents that need a deterministic interface instead of scraping HTML or pretending to be a browser.

Features

• Structured JSON errors with useful exit codes
• JSON-first output everywhere
• token + base-url config via env or config file
• profile read/update
• links list/create/update/delete/reorder/sync
• shorts list/create/update/toggle/delete/QR download
• analytics summary + links + shorts
• auth doctor for config/auth sanity checks
• GitHub Actions CI smoke coverage

Requirements

• Node.js 20+
• XRPL Social agent token with the scopes you need

Install

Run from source

git clone https://github.com/danielwwf/xrpl-social-cli.git
cd xrpl-social-cli
node bin/xrplsocial.js --help

Global install from local checkout

npm install -g .
xrplsocial --help

Quick start

xrplsocial config init   --base-url https://dev.xrpl.social   --token xrsoc_pat_...

xrplsocial auth doctor
xrplsocial profile get
xrplsocial links list
xrplsocial analytics summary --window 7d

Config

Show effective config

xrplsocial config show

Use env vars instead

export XRPLSOCIAL_BASE_URL="https://xrpl.social"
export XRPLSOCIAL_TOKEN="xrsoc_pat_..."

Config file path:

• ~/.config/xrplsocial/config.json

Use dev on purpose

xrplsocial config init --base-url https://dev.xrpl.social --token xrsoc_pat_...

Command overview

xrplsocial auth whoami
xrplsocial auth doctor
xrplsocial config show
xrplsocial config init --base-url https://xrpl.social --token xrsoc_pat_...
xrplsocial profile get
xrplsocial profile update --title "My title"
xrplsocial links list
xrplsocial links create --label "Homepage" --url https://example.com
xrplsocial links update --id 123 --label "Homepage" --url https://example.com/new
xrplsocial links delete --id 123
xrplsocial links reorder --file order.json
xrplsocial links sync --file links.json
xrplsocial links sync --file links.json --delete-missing
xrplsocial links export --out links.json
xrplsocial shorts list
xrplsocial shorts create --title "Launch" --destination-url https://example.com
xrplsocial shorts update --id 123 --destination-url https://example.com/updated --title "Updated"
xrplsocial shorts toggle --id 123
xrplsocial shorts delete --id 123
xrplsocial shorts qr --id 123 --out short-123.png
xrplsocial analytics summary
xrplsocial analytics summary --window 7d
xrplsocial analytics links --window 7d
xrplsocial analytics shorts --window 7d
xrplsocial analytics export --kind summary --window 7d --out analytics.json

Examples

• examples/links-sync.json
• examples/links-reorder.json

File shapes

links sync

{
  "links": [
    {"label": "Homepage", "url": "https://example.com"},
    {"label": "Docs", "url": "https://docs.example.com"}
  ]
}

links reorder

{
  "order": [123, 456, 789]
}

Notes

• Delete is defensive by default. Missing links are only removed when --delete-missing is passed.
• Reorder expects the full owned link id set, not only a partial subset.
• Do not put real tokens into shell history on shared machines. Prefer config file or env management.

Development

npm run ci

Release flow

• see RELEASING.md
• GitHub Actions package check on tags/workflow dispatch
• npm pack used as packaging sanity gate

License

MIT