bitsocial-cli: A Bitsocial Node with WebSocket and Command Line Interface

Table of contents

• What is Bitsocial?
• What is bitsocial-cli?
• Install
• Docker
• Usage
• Commands
• Contribution
• Feedback

What is Bitsocial?

Bitsocial is p2p and decentralized social media protocol built completely with IPFS/IPNS/pubsub. It doesn't use any central server, central database, public HTTP endpoint or DNS, it is pure peer to peer and fully content addressable. It will allow community owners to retain full ownership over their community. Learn more here.

What is bitsocial-cli?

bitsocial-cli is an interface to the backend of PKC protocol using pkc-js. Users can run and manage their communities using it. It is written in Typescript and designed to receive commands via CLI and WebSocket.

• Runs an IPFS and Bitsocial node
• Command Line interface to manage Bitsocial communities
• WebSocket RPC to access and control your communities and publications
• Includes Web UIs like Seedit where you can browse the network and manage your community

Install

Requires Node.js 22.19 or later. We recommend using nvm to install and manage Node.js versions.

npm install -g @bitsocial/bitsocial-cli

To install a specific version:

npm install -g @bitsocial/[email protected]

To update to the latest version:

bitsocial update install

Build from source (optional)

If you want to build from source directly:

git clone https://github.com/bitsocialnet/bitsocial-cli
cd bitsocial-cli
npm ci
npm run build
npx oclif manifest
npm run ci:download-web-uis
./bin/run --help

After running the last command you should be able to run commands directly against ./bin/run, for example ./bin/run daemon

Docker

You can run bitsocial-cli as a Docker container. The container runs the daemon and exposes the RPC + web UI on port 9138, the Kubo IPFS API on port 50019, and the IPFS Gateway on port 6473.

Once your container is running, you can use one of the bundled web UIs to browse the Bitsocial network and manage your communities -- no CLI commands needed. The web UIs provide a full-featured interface for creating communities, moderating, and browsing content entirely through your browser. All the Web UIs are interopable so you can post and read from whichever you like and you can see your own content on each client.

If you're a power user, you can also run CLI commands against the running container with docker exec:

docker exec bitsocial bitsocial community list

Data paths inside the container

The Docker volumes bitsocial-data:/data and bitsocial-logs:/logs are mapped to /data and /logs inside the container. The bitsocial subdirectory is created automatically by the application.

Docker Compose (recommended)

Copy the example compose file and start the node:

cp docker-compose.example.yml docker-compose.yml
docker compose up -d

View the startup logs to find your auth key URL:

docker compose logs -f

The output will include lines like:

pkc rpc: listening on ws://localhost:9138/<auth-key> (secret auth key for remote connections)
WebUI (seedit - Similar to old reddit UI): http://<your-ip>:9138/<auth-key>/seedit (secret auth key for remote connections)

Open the WebUI URL in your browser to start using Bitsocial.

Viewing logs

There are two ways to view logs from a Docker container:

Quick logs — shows stdout output only (startup messages, errors):

docker compose logs -f          # Docker Compose
docker logs -f bitsocial        # Docker Run

Full debug logs — shows the complete daemon log including debug/trace output:

docker exec bitsocial bitsocial logs -f

The bitsocial logs command supports several filtering flags:

docker exec bitsocial bitsocial logs -f              # follow (stream new lines)
docker exec bitsocial bitsocial logs -n 100           # last 100 lines
docker exec bitsocial bitsocial logs --since 1h       # entries from the last hour
docker exec bitsocial bitsocial logs --until 30m      # entries up to 30 minutes ago

Debug and trace logs are written only to the log file, not to stdout, so docker logs will not show them. Use bitsocial logs inside the container for the full picture.

Example docker-compose.yml

services:
  bitsocial:
    image: ghcr.io/bitsocialnet/bitsocial-cli:latest
    container_name: bitsocial
    restart: unless-stopped
    ports:
      - "9138:9138"    # PKC RPC + Web UI
      - "50019:50019"  # Kubo IPFS API
      - "6473:6473"    # IPFS Gateway
    volumes:
      - bitsocial-data:/data
      - bitsocial-logs:/logs
    environment:
      - DEBUG=bitsocial*, pkc*, -pkc*trace
      # Set a fixed auth key (useful for bookmarking the web UI URL).
      # If left unset, a random key is generated on first start.
      # - PKC_RPC_AUTH_KEY=your-custom-auth-key-here
      # Override Kubo IPFS bind addresses / ports:
      # - KUBO_RPC_URL=http://0.0.0.0:50019/api/v0
      # - IPFS_GATEWAY_URL=http://0.0.0.0:6473

volumes:
  bitsocial-data:
  bitsocial-logs:

Docker Run

docker run -d \
  --name bitsocial \
  --restart unless-stopped \
  -p 9138:9138 \
  -p 50019:50019 \
  -p 6473:6473 \
  -v bitsocial-data:/data \
  -v bitsocial-logs:/logs \
  ghcr.io/bitsocialnet/bitsocial-cli:latest

With a custom auth key:

docker run -d \
  --name bitsocial \
  --restart unless-stopped \
  -p 9138:9138 \
  -p 50019:50019 \
  -p 6473:6473 \
  -v bitsocial-data:/data \
  -v bitsocial-logs:/logs \
  -e PKC_RPC_AUTH_KEY=my-secret-key \
  ghcr.io/bitsocialnet/bitsocial-cli:latest

Building the Docker image locally

docker build -t bitsocial-cli .
docker run -p 9138:9138 -p 50019:50019 -p 6473:6473 bitsocial-cli

Usage

The data/config directory of Bitsocial

This is the default directory where bitsocial-cli will keep its config, as well as data for local communities:

• macOS: ~/Library/Application Support/bitsocial
• Windows: %LOCALAPPDATA%\bitsocial
• Linux: ~/.local/share/bitsocial

The logs directory of Bitsocial

bitsocial-cli will keep logs in this directory, with a cap of 10M per log file.

• macOS: ~/Library/Logs/bitsocial
• Windows: %LOCALAPPDATA%\bitsocial\Log
• Linux: ~/.local/state/bitsocial

Running Daemon

In Bash (or powershell if you're on Windows), run bitsocial daemon to able to connect to the network. You need to have the bitsocial daemon terminal running to be able to execute other commands.

$ bitsocial daemon
IPFS API listening on: http://localhost:5001/api/v0
IPFS Gateway listening on: http://localhost:6473
pkc rpc: listening on ws://localhost:9138 (local connections only)
pkc rpc: listening on ws://localhost:9138/MHA1tm2QWG19z0bnkRarDNWIajDobl7iN2eM2PmL (secret auth key for remote connections)
Bitsocial data path: /root/.local/share/bitsocial
Communities in data path:  [ 'anime-and-manga.bso' ]
WebUI (5chan - Imageboard-style UI): http://localhost:9138/MHA1tm2QWG19z0bnkRarDNWIajDobl7iN2eM2PmL/5chan (local connections only)
WebUI (5chan - Imageboard-style UI): http://192.168.1.60:9138/MHA1tm2QWG19z0bnkRarDNWIajDobl7iN2eM2PmL/5chan (secret auth key for remote connections)
WebUI (seedit - Similar to old reddit UI): http://localhost:9138/MHA1tm2QWG19z0bnkRarDNWIajDobl7iN2eM2PmL/seedit (local connections only)
WebUI (seedit - Similar to old reddit UI): http://192.168.1.60:9138/MHA1tm2QWG19z0bnkRarDNWIajDobl7iN2eM2PmL/seedit (secret auth key for remote connections)

Once bitsocial daemon is running, you can create and manage your communities through the web interfaces, either seedit or 5chan. All the interfaces are interoperable. If you're a power user and prefer CLI, then you can take a look at the commands below.

If you need to view detailed protocol or IPFS logs for debugging, you can use bitsocial logs. For example, bitsocial logs --tail 50 shows the last 50 lines, or bitsocial logs --since 1h shows logs from the past hour.

Making your node reachable from browsers

This sets up two of the ways a browser can dial a node: WebSocket Secure, which needs a certificate browsers trust, and WebTransport. Without either, the daemon prints a line at start saying browsers cannot reach this node. To fix that, run this while the daemon is running:

$ bitsocial reachability setup

It finds this machine's public addresses, asks the router to forward ports through UPnP if it is behind NAT, gets a Let's Encrypt certificate for the IP address (or for your domain with --domain), configures kubo and checks the result. It is safe to rerun. The daemon then keeps Caddy running, renews certificates and follows IP changes.

status and setup both check what this machine needs and say how to fix anything missing: permission for Caddy and kubo to bind port 443 (kubo otherwise keeps running and silently does not listen on UDP 443), whether TCP 80, TCP 443 and UDP 443 are held by another program, an active ufw or firewalld, and what kubo is really listening on. Nothing on the machine can prove inbound traffic reaches it, or see a cloud provider's firewall, so test from another network too.

Already serving WSS without setup? If you run your own reverse proxy, or kubo has an AutoTLS address, you do not need setup. status and the daemon try a real libp2p handshake with each WSS address kubo announces and report the result, and they only say browsers cannot reach the node if every handshake definitely failed. The handshake runs from this machine, so a success does not prove other networks can connect, and behind a router a failure only gets a warning, as the router may not connect a machine to its own public address.

• Port 443 already in use: pass --domain, and setup prints a snippet for nginx, Apache or Caddy that forwards the name to kubo. Then pass --announce with the address your server serves. It is announced only after a real libp2p handshake through it succeeds.
• Linux, not root: Caddy and kubo both need to bind port 443. sudo sysctl -w net.ipv4.ip_unprivileged_port_start=443 covers both; persist it in /etc/sysctl.d/. Setup offers to run setcap on Caddy instead, and prints what kubo needs if it could not bind UDP 443.
• Docker: add cap_add: [NET_BIND_SERVICE] and publish 443:443/tcp, 443:443/udp and 80:80/tcp.
• Windows: setup prints the firewall rules to add.
• Testing: --staging uses the Let's Encrypt staging CA, whose certificates browsers do not trust.

See docs/reachability.md for how it works, choosing a path and troubleshooting.

Caddy is downloaded on the first setup from its GitHub release and checked against a hash pinned in this repository. State lives in <data path>/reachability/. Running setup means accepting the Let's Encrypt Subscriber Agreement; no email address is sent.

Creating your first community

$ bitsocial community create --title "Hello World!" --description "This is gonna be great"
12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu

Listing all your communities

$ bitsocial community list
Address                                              Started
 ──────────────────────────────────────────────────── ───────
 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu true
 business-and-finance.bso                             true
 censorship-watch.bso                                 true
 health-nutrition-science.bso                         true
 movies-tv-anime.bso                                  true
 anime-and-manga.bso                                  true
 politically-incorrect.bso                            true
 reddit-screenshots.bso                               false
 videos-livestreams-podcasts.bso                      false

Adding a role moderator to your community

$ bitsocial community edit mysub.bso '--roles["author-address.bso"].role' moderator

Adding a role owner to your community

$ bitsocial community edit mysub.bso '--roles["author-address.bso"].role' owner

Adding a role admin to your community

$ bitsocial community edit mysub.bso '--roles["author-address.bso"].role' admin

Removing a role

$ bitsocial community edit mysub.bso '--roles["author-address.bso"]' null

Commands

• bitsocial challenge add PACKAGE
• bitsocial challenge i PACKAGE
• bitsocial challenge install PACKAGE
• bitsocial challenge list
• bitsocial challenge ls
• bitsocial challenge remove NAME
• bitsocial challenge rm NAME
• bitsocial challenge un NAME
• bitsocial challenge uninstall NAME
• bitsocial community create
• bitsocial community delete ADDRESSES
• bitsocial community edit ADDRESS
• bitsocial community export [ADDRESS]
• bitsocial community get [ADDRESS]
• bitsocial community list
• bitsocial community start ADDRESSES
• bitsocial community stop ADDRESSES
• bitsocial daemon
• bitsocial help [COMMAND]
• bitsocial logs
• bitsocial page-sort add PACKAGE
• bitsocial page-sort i PACKAGE
• bitsocial page-sort install PACKAGE
• bitsocial page-sort list
• bitsocial page-sort ls
• bitsocial page-sort remove NAME
• bitsocial page-sort rm NAME
• bitsocial page-sort un NAME
• bitsocial page-sort uninstall NAME
• bitsocial reachability disable
• bitsocial reachability enable
• bitsocial reachability setup
• bitsocial reachability status
• bitsocial update check
• bitsocial update install [VERSION]
• bitsocial update versions

bitsocial challenge add PACKAGE

Install a challenge package (npm package name, git URL, tarball URL, or local path)

USAGE
  $ bitsocial challenge add PACKAGE --pkcRpcUrl <value> [--pkcOptions.dataPath <value>]

ARGUMENTS
  PACKAGE  Package specifier — anything npm can install (name, name@version, git URL, tarball URL, local path)

FLAGS
  --pkcOptions.dataPath=<value>  Data path to install the challenge into
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Install a challenge package (npm package name, git URL, tarball URL, or local path)

ALIASES
  $ bitsocial challenge i
  $ bitsocial challenge add

EXAMPLES
  $ bitsocial challenge install @bitsocial/mintpass-challenge

  $ bitsocial challenge install @bitsocial/[email protected]

  $ bitsocial challenge install github:user/repo

  $ bitsocial challenge install https://example.com/my-challenge-1.0.0.tar.gz

  $ bitsocial challenge install ./my-local-challenge

bitsocial challenge i PACKAGE

Install a challenge package (npm package name, git URL, tarball URL, or local path)

USAGE
  $ bitsocial challenge i PACKAGE --pkcRpcUrl <value> [--pkcOptions.dataPath <value>]

ARGUMENTS
  PACKAGE  Package specifier — anything npm can install (name, name@version, git URL, tarball URL, local path)

FLAGS
  --pkcOptions.dataPath=<value>  Data path to install the challenge into
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Install a challenge package (npm package name, git URL, tarball URL, or local path)

ALIASES
  $ bitsocial challenge i
  $ bitsocial challenge add

EXAMPLES
  $ bitsocial challenge install @bitsocial/mintpass-challenge

  $ bitsocial challenge install @bitsocial/[email protected]

  $ bitsocial challenge install github:user/repo

  $ bitsocial challenge install https://example.com/my-challenge-1.0.0.tar.gz

  $ bitsocial challenge install ./my-local-challenge

bitsocial challenge install PACKAGE

Install a challenge package (npm package name, git URL, tarball URL, or local path)

USAGE
  $ bitsocial challenge install PACKAGE --pkcRpcUrl <value> [--pkcOptions.dataPath <value>]

ARGUMENTS
  PACKAGE  Package specifier — anything npm can install (name, name@version, git URL, tarball URL, local path)

FLAGS
  --pkcOptions.dataPath=<value>  Data path to install the challenge into
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Install a challenge package (npm package name, git URL, tarball URL, or local path)

ALIASES
  $ bitsocial challenge i
  $ bitsocial challenge add

EXAMPLES
  $ bitsocial challenge install @bitsocial/mintpass-challenge

  $ bitsocial challenge install @bitsocial/[email protected]

  $ bitsocial challenge install github:user/repo

  $ bitsocial challenge install https://example.com/my-challenge-1.0.0.tar.gz

  $ bitsocial challenge install ./my-local-challenge

See code: src/cli/commands/challenge/install.ts

bitsocial challenge list

List installed challenge packages

USAGE
  $ bitsocial challenge list [-q] [--pkcOptions.dataPath <value>]

FLAGS
  -q, --quiet                        Only display challenge names
      --pkcOptions.dataPath=<value>  Data path where challenges are installed

DESCRIPTION
  List installed challenge packages

ALIASES
  $ bitsocial challenge ls

EXAMPLES
  $ bitsocial challenge list

  $ bitsocial challenge list -q

See code: src/cli/commands/challenge/list.ts

bitsocial challenge ls

List installed challenge packages

USAGE
  $ bitsocial challenge ls [-q] [--pkcOptions.dataPath <value>]

FLAGS
  -q, --quiet                        Only display challenge names
      --pkcOptions.dataPath=<value>  Data path where challenges are installed

DESCRIPTION
  List installed challenge packages

ALIASES
  $ bitsocial challenge ls

EXAMPLES
  $ bitsocial challenge list

  $ bitsocial challenge list -q

bitsocial challenge remove NAME

Remove an installed challenge package. Refuses while a community's settings.challenges still names it, unless --force is passed

USAGE
  $ bitsocial challenge remove NAME --pkcRpcUrl <value> [--pkcOptions.dataPath <value>] [--force]

ARGUMENTS
  NAME  The challenge package name (e.g., my-challenge or @scope/my-challenge)

FLAGS
  --force                        Remove without checking whether communities still use it (the daemon is not contacted
                                 for the check)
  --pkcOptions.dataPath=<value>  Data path where challenges are installed
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Remove an installed challenge package. Refuses while a community's settings.challenges still names it, unless --force
  is passed

ALIASES
  $ bitsocial challenge uninstall
  $ bitsocial challenge rm
  $ bitsocial challenge un

EXAMPLES
  $ bitsocial challenge remove my-challenge

  $ bitsocial challenge remove @scope/my-challenge

  $ bitsocial challenge remove my-challenge --force

See code: src/cli/commands/challenge/remove.ts

bitsocial challenge rm NAME

Remove an installed challenge package. Refuses while a community's settings.challenges still names it, unless --force is passed

USAGE
  $ bitsocial challenge rm NAME --pkcRpcUrl <value> [--pkcOptions.dataPath <value>] [--force]

ARGUMENTS
  NAME  The challenge package name (e.g., my-challenge or @scope/my-challenge)

FLAGS
  --force                        Remove without checking whether communities still use it (the daemon is not contacted
                                 for the check)
  --pkcOptions.dataPath=<value>  Data path where challenges are installed
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Remove an installed challenge package. Refuses while a community's settings.challenges still names it, unless --force
  is passed

ALIASES
  $ bitsocial challenge uninstall
  $ bitsocial challenge rm
  $ bitsocial challenge un

EXAMPLES
  $ bitsocial challenge remove my-challenge

  $ bitsocial challenge remove @scope/my-challenge

  $ bitsocial challenge remove my-challenge --force

bitsocial challenge un NAME

Remove an installed challenge package. Refuses while a community's settings.challenges still names it, unless --force is passed

USAGE
  $ bitsocial challenge un NAME --pkcRpcUrl <value> [--pkcOptions.dataPath <value>] [--force]

ARGUMENTS
  NAME  The challenge package name (e.g., my-challenge or @scope/my-challenge)

FLAGS
  --force                        Remove without checking whether communities still use it (the daemon is not contacted
                                 for the check)
  --pkcOptions.dataPath=<value>  Data path where challenges are installed
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Remove an installed challenge package. Refuses while a community's settings.challenges still names it, unless --force
  is passed

ALIASES
  $ bitsocial challenge uninstall
  $ bitsocial challenge rm
  $ bitsocial challenge un

EXAMPLES
  $ bitsocial challenge remove my-challenge

  $ bitsocial challenge remove @scope/my-challenge

  $ bitsocial challenge remove my-challenge --force

bitsocial challenge uninstall NAME

Remove an installed challenge package. Refuses while a community's settings.challenges still names it, unless --force is passed

USAGE
  $ bitsocial challenge uninstall NAME --pkcRpcUrl <value> [--pkcOptions.dataPath <value>] [--force]

ARGUMENTS
  NAME  The challenge package name (e.g., my-challenge or @scope/my-challenge)

FLAGS
  --force                        Remove without checking whether communities still use it (the daemon is not contacted
                                 for the check)
  --pkcOptions.dataPath=<value>  Data path where challenges are installed
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Remove an installed challenge package. Refuses while a community's settings.challenges still names it, unless --force
  is passed

ALIASES
  $ bitsocial challenge uninstall
  $ bitsocial challenge rm
  $ bitsocial challenge un

EXAMPLES
  $ bitsocial challenge remove my-challenge

  $ bitsocial challenge remove @scope/my-challenge

  $ bitsocial challenge remove my-challenge --force

bitsocial community create

Create a community with specific properties. A newly created community will be started after creation and be able to receive publications. For a list of properties, visit https://github.com/pkcprotocol/pkc-js

USAGE
  $ bitsocial community create --pkcRpcUrl <value> [--privateKeyPath <value>] [-f <value>]

FLAGS
  -f, --jsonFile=<value>        Path to a JSON/JSONC file containing create options (supports comments)
      --pkcRpcUrl=<value>       (required) [default: ws://localhost:9138/] URL to PKC RPC
      --privateKeyPath=<value>  Private key (PEM) of the community signer that will be used to determine address (if
                                address is not a domain). If it's not provided then PKC will generate a private key

DESCRIPTION
  Create a community with specific properties. A newly created community will be started after creation and be able to
  receive publications. For a list of properties, visit https://github.com/pkcprotocol/pkc-js

EXAMPLES
  Create a community with title 'Hello Plebs' and description 'Welcome'

    $ bitsocial community create --title 'Hello Plebs' --description 'Welcome'

  Create a community using options from a JSON/JSONC file

    $ bitsocial community create --jsonFile ./create-options.json

See code: src/cli/commands/community/create.ts

bitsocial community delete ADDRESSES

Delete a community permanently.

USAGE
  $ bitsocial community delete ADDRESSES... --pkcRpcUrl <value>

ARGUMENTS
  ADDRESSES...  Addresses of communities to delete. Separated by space

FLAGS
  --pkcRpcUrl=<value>  (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Delete a community permanently.

EXAMPLES
  $ bitsocial community delete plebbit.bso

  $ bitsocial community delete 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu

See code: src/cli/commands/community/delete.ts

bitsocial community edit ADDRESS

Edit a community's properties. For a list of properties, visit https://github.com/pkcprotocol/pkc-js

USAGE
  $ bitsocial community edit ADDRESS --pkcRpcUrl <value> [-f <value>]

ARGUMENTS
  ADDRESS  Address of the community to edit. It could be the name domain, or a public key

FLAGS
  -f, --jsonFile=<value>   Path to a JSON/JSONC file containing edit options (supports comments)
      --pkcRpcUrl=<value>  (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Edit a community's properties. For a list of properties, visit https://github.com/pkcprotocol/pkc-js

  Merge behavior with CLI flags:
  - Objects are merged with the community's current state (new keys are added, existing keys are overwritten).
  - Arrays are extended: new values are prepended to the existing array.
  - Setting a value to null removes it (e.g. --roles['mod.bso'] null).

  Merge behavior with --jsonFile:
  - Objects are merged the same way as CLI flags.
  - Arrays are replaced entirely (RFC 7396 JSON Merge Patch semantics).
  - When both --jsonFile and CLI flags are provided, CLI flags take priority.

  For modifying complex settings like challenges, consider using a web UI instead:
  https://bitsocial.net/projects?category=apps

EXAMPLES
  Change the name of the community

    $ bitsocial community edit 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu --name newName.bso

  Add the author address 'esteban.bso' as an admin on the community

    $ bitsocial community edit mycommunity.bso '--roles["esteban.bso"].role' admin

  Add two challenges to the community. The first challenge will be a question and answer, and the second will be a
  math question

    $ bitsocial community edit mycommunity.bso '--settings.challenges[0].name' question \
      '--settings.challenges[0].options.question' "what is the password?" '--settings.challenges[0].options.answer' \
      thepassword '--settings.challenges[1].name' text-math

  Use an installed page sort package (bitsocial page-sort install @pkcprotocol/active-page-sort) as the preloaded
  posts sort, where replies containing 'sage' do not bump a thread

    $ bitsocial community edit mycommunity.bso '--settings.pages.posts[0].name' @pkcprotocol/active-page-sort \
      '--settings.pages.posts[0].options.noBumpKeywords' sage '--settings.pages.posts[0].preloaded' true

  Change the title and description

    $ bitsocial community edit mycommunity.bso --title "This is the new title" --description "This is the new \
      description"

  Remove a role from a moderator/admin/owner

    $ bitsocial community edit bitsocial.bso '--roles["rinse12.bso"]' null

  Enable settings.fetchThumbnailUrls to fetch the thumbnail of url submitted by authors

    $ bitsocial community edit bitsocial.bso --settings.fetchThumbnailUrls

  disable settings.fetchThumbnailUrls

    $ bitsocial community edit bitsocial.bso --settings.fetchThumbnailUrls=false

  Edit a community using options from a JSON/JSONC file

    $ bitsocial community edit bitsocial.bso --jsonFile ./edit-options.json

See code: src/cli/commands/community/edit.ts

bitsocial community export [ADDRESS]

Export a local community to a SQLite snapshot file. The export runs on the RPC server (daemon); once finished the snapshot is downloaded and its sha256 checksum is verified. Pass --includePrivateKey to produce a restorable backup that keeps the community's address.

USAGE
  $ bitsocial community export [ADDRESS] --pkcRpcUrl <value> [--name <value>] [--publicKey <value>] [-o <value>]
    [--includePrivateKey] [--force] [-q]

ARGUMENTS
  [ADDRESS]  Address of the community to export

FLAGS
  -o, --path=<value>       Destination file for the downloaded snapshot (default:
                           <dataPath>/exports/<address>_<datetime>.sqlite)
  -q, --quiet              Suppress progress output; only print the path of the downloaded snapshot
      --force              Overwrite the destination file if it already exists
      --includePrivateKey  Ask the RPC server to include the community signer's private key in the export. Required for
                           a restorable backup that keeps the same community address. The daemon may refuse (see
                           `bitsocial daemon --no-allowPrivateKeyExport`)
      --name=<value>       Name of the community to export
      --pkcRpcUrl=<value>  (required) [default: ws://localhost:9138/] URL to PKC RPC
      --publicKey=<value>  Public key of the community to export

DESCRIPTION
  Export a local community to a SQLite snapshot file. The export runs on the RPC server (daemon); once finished the
  snapshot is downloaded and its sha256 checksum is verified. Pass --includePrivateKey to produce a restorable backup
  that keeps the community's address.

EXAMPLES
  $ bitsocial community export plebmusic.bso

  $ bitsocial community export plebmusic.bso --includePrivateKey -o ./backups/plebmusic.sqlite

  $ bitsocial community export --name my-community

  $ bitsocial community export --publicKey 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu

See code: src/cli/commands/community/export.ts

bitsocial community get [ADDRESS]

Fetch a local or remote community, and print its json in the terminal

USAGE
  $ bitsocial community get [ADDRESS] --pkcRpcUrl <value> [--name <value>] [--publicKey <value>]

ARGUMENTS
  [ADDRESS]  Address of the community to fetch

FLAGS
  --name=<value>       Name of the community to fetch
  --pkcRpcUrl=<value>  (required) [default: ws://localhost:9138/] URL to PKC RPC
  --publicKey=<value>  Public key of the community to fetch

DESCRIPTION
  Fetch a local or remote community, and print its json in the terminal

EXAMPLES
  $ bitsocial community get plebmusic.bso

  $ bitsocial community get 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu

  $ bitsocial community get --name my-community

  $ bitsocial community get --publicKey 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu

See code: src/cli/commands/community/get.ts

bitsocial community list

List your communities

USAGE
  $ bitsocial community list --pkcRpcUrl <value> [-q]

FLAGS
  -q, --quiet              Only display community addresses, one per line
      --pkcRpcUrl=<value>  (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  List your communities

EXAMPLES
  $ bitsocial community list -q

  $ bitsocial community list

See code: src/cli/commands/community/list.ts

bitsocial community start ADDRESSES

Start a community

USAGE
  $ bitsocial community start ADDRESSES... --pkcRpcUrl <value> [--concurrency <value>]

ARGUMENTS
  ADDRESSES...  Addresses of communities to start. Separated by space

FLAGS
  --concurrency=<value>  [default: 5] Number of communities to start in parallel
  --pkcRpcUrl=<value>    (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Start a community

EXAMPLES
  $ bitsocial community start plebbit.bso

  $ bitsocial community start 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu

  Start all communities in your data path

    $ bitsocial community start $(bitsocial community list -q)

  Start communities sequentially (no concurrency)

    $ bitsocial community start $(bitsocial community list -q) --concurrency 1

See code: src/cli/commands/community/start.ts

bitsocial community stop ADDRESSES

Stop a community. The community will not publish or receive any publications until it is started again.

USAGE
  $ bitsocial community stop ADDRESSES... --pkcRpcUrl <value>

ARGUMENTS
  ADDRESSES...  Addresses of communities to stop. Separated by space

FLAGS
  --pkcRpcUrl=<value>  (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Stop a community. The community will not publish or receive any publications until it is started again.

EXAMPLES
  $ bitsocial community stop plebbit.bso

  $ bitsocial community stop Qmb99crTbSUfKXamXwZBe829Vf6w5w5TktPkb6WstC9RFW

See code: src/cli/commands/community/stop.ts

bitsocial daemon

Run a network-connected Bitsocial node. Once the daemon is running you can create and start your communities and receive publications from users. The daemon will also serve web ui on http that can be accessed through a browser on any machine. Within the web ui users are able to browse, create and manage their communities fully P2P.

USAGE
  $ bitsocial daemon --pkcRpcUrl <value> --logPath <value> [--chainProviderUrls <value>...] [--enableIpfsGc]
    [--ipfsGcIntervalMinutes <value>] [--allowPrivateKeyExport]

FLAGS
  --[no-]allowPrivateKeyExport     Allow RPC clients to request community exports that include the community signer's
                                   private key (`bitsocial community export --includePrivateKey`). Disable with
                                   --no-allowPrivateKeyExport when exposing the RPC to untrusted clients
  --chainProviderUrls=<value>...   [default:
                                   https://eth.drpc.org,https://ethereum.publicnode.com,https://ethereum-rpc.publicnode.
                                   com,https://rpc.mevblocker.io,https://1rpc.io/eth,https://eth-pokt.nodies.app] RPC
                                   URL(s) for .bso name resolution. Can be specified multiple times.
  --[no-]enableIpfsGc              Periodically garbage-collect the IPFS repo over the kubo RPC API while the daemon is
                                   up. Only reclaims unpinned blocks — pinned data and MFS are never collected. Disable
                                   with --no-enableIpfsGc
  --ipfsGcIntervalMinutes=<value>  [default: 60] How often to garbage-collect the IPFS repo, in minutes
  --logPath=<value>                (required) [default: /home/runner/.local/state/bitsocial] Specify a directory which
                                   will be used to store logs
  --pkcRpcUrl=<value>              (required) [default: ws://localhost:9138/] Specify PKC RPC URL to listen on

DESCRIPTION
  Run a network-connected Bitsocial node. Once the daemon is running you can create and start your communities and
  receive publications from users. The daemon will also serve web ui on http that can be accessed through a browser on
  any machine. Within the web ui users are able to browse, create and manage their communities fully P2P.
  Options can be passed to the RPC's instance through flag --pkcOptions.optionName. For a list of pkc options
  (https://github.com/pkcprotocol/pkc-js?tab=readme-ov-file#pkcoptions)
  If you need to modify ipfs config, you should head to {bitsocial-data-path}/.bitsocial-cli.ipfs/config (or
  $IPFS_PATH/config if set) and modify the config file


EXAMPLES
  $ bitsocial daemon

  $ bitsocial daemon --pkcRpcUrl ws://localhost:53812

  $ bitsocial daemon --pkcOptions.dataPath /tmp/bitsocial-datapath/

  $ bitsocial daemon '--pkcOptions.kuboRpcClientsOptions[0]' https://remoteipfsnode.com

  $ bitsocial daemon --chainProviderUrls https://mainnet.infura.io/v3/YOUR_KEY

  $ bitsocial daemon --no-allowPrivateKeyExport

See code: src/cli/commands/daemon.ts

bitsocial help [COMMAND]

Display help for bitsocial.

USAGE
  $ bitsocial help [COMMAND...] [-n]

ARGUMENTS
  [COMMAND...]  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for bitsocial.

See code: @oclif/plugin-help

bitsocial logs

View the latest BitSocial daemon log file. By default dumps the full log and exits. Use --follow to stream new output in real-time (like tail -f).

USAGE
  $ bitsocial logs [-f] [-n <value>] [--since <value>] [--until <value>] [--logPath <value>] [--stdout |
    --stderr]

FLAGS
  -f, --follow           Follow log output in real-time (like tail -f)
  -n, --tail=<value>     [default: all] Number of log entries to show from the end. Use "all" to show everything.
      --logPath=<value>  Specify the directory containing log files
      --since=<value>    Show logs since timestamp (ISO 8601, e.g. 2026-01-02T13:23:37Z) or relative time (e.g. 30s,
                         42m, 2h, 1d)
      --stderr           Show only stderr log entries (output of pkc-logger library)
      --stdout           Show only stdout log entries
      --until=<value>    Show logs before timestamp (ISO 8601, e.g. 2026-01-02T13:23:37Z) or relative time (e.g. 30s,
                         42m, 2h, 1d)

DESCRIPTION
  View the latest BitSocial daemon log file. By default dumps the full log and exits. Use --follow to stream new output
  in real-time (like tail -f).

EXAMPLES
  $ bitsocial logs

  $ bitsocial logs -f

  $ bitsocial logs -n 50

  $ bitsocial logs --since 5m

  $ bitsocial logs --since 2026-01-02T13:23:37Z --until 2026-01-02T14:00:00Z

  $ bitsocial logs --since 1h -f

  $ bitsocial logs --stdout

  $ bitsocial logs --stderr

  $ bitsocial logs --stdout -f

See code: src/cli/commands/logs.ts

bitsocial page-sort add PACKAGE

Install a page sort package (npm package name, git URL, tarball URL, or local path)

USAGE
  $ bitsocial page-sort add PACKAGE --pkcRpcUrl <value> [--pkcOptions.dataPath <value>]

ARGUMENTS
  PACKAGE  Package specifier — anything npm can install (name, name@version, git URL, tarball URL, local path)

FLAGS
  --pkcOptions.dataPath=<value>  Data path to install the page sort into
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Install a page sort package (npm package name, git URL, tarball URL, or local path)

ALIASES
  $ bitsocial page-sort i
  $ bitsocial page-sort add

EXAMPLES
  $ bitsocial page-sort install @pkcprotocol/active-page-sort

  $ bitsocial page-sort install @pkcprotocol/[email protected]

  $ bitsocial page-sort install ./my-local-page-sort

bitsocial page-sort i PACKAGE

Install a page sort package (npm package name, git URL, tarball URL, or local path)

USAGE
  $ bitsocial page-sort i PACKAGE --pkcRpcUrl <value> [--pkcOptions.dataPath <value>]

ARGUMENTS
  PACKAGE  Package specifier — anything npm can install (name, name@version, git URL, tarball URL, local path)

FLAGS
  --pkcOptions.dataPath=<value>  Data path to install the page sort into
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Install a page sort package (npm package name, git URL, tarball URL, or local path)

ALIASES
  $ bitsocial page-sort i
  $ bitsocial page-sort add

EXAMPLES
  $ bitsocial page-sort install @pkcprotocol/active-page-sort

  $ bitsocial page-sort install @pkcprotocol/[email protected]

  $ bitsocial page-sort install ./my-local-page-sort

bitsocial page-sort install PACKAGE

Install a page sort package (npm package name, git URL, tarball URL, or local path)

USAGE
  $ bitsocial page-sort install PACKAGE --pkcRpcUrl <value> [--pkcOptions.dataPath <value>]

ARGUMENTS
  PACKAGE  Package specifier — anything npm can install (name, name@version, git URL, tarball URL, local path)

FLAGS
  --pkcOptions.dataPath=<value>  Data path to install the page sort into
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Install a page sort package (npm package name, git URL, tarball URL, or local path)

ALIASES
  $ bitsocial page-sort i
  $ bitsocial page-sort add

EXAMPLES
  $ bitsocial page-sort install @pkcprotocol/active-page-sort

  $ bitsocial page-sort install @pkcprotocol/[email protected]

  $ bitsocial page-sort install ./my-local-page-sort

See code: src/cli/commands/page-sort/install.ts

bitsocial page-sort list

List installed page sort packages

USAGE
  $ bitsocial page-sort list [-q] [--pkcOptions.dataPath <value>]

FLAGS
  -q, --quiet                        Only display page sort names
      --pkcOptions.dataPath=<value>  Data path where page sorts are installed

DESCRIPTION
  List installed page sort packages

ALIASES
  $ bitsocial page-sort ls

EXAMPLES
  $ bitsocial page-sort list

  $ bitsocial page-sort list -q

See code: src/cli/commands/page-sort/list.ts

bitsocial page-sort ls

List installed page sort packages

USAGE
  $ bitsocial page-sort ls [-q] [--pkcOptions.dataPath <value>]

FLAGS
  -q, --quiet                        Only display page sort names
      --pkcOptions.dataPath=<value>  Data path where page sorts are installed

DESCRIPTION
  List installed page sort packages

ALIASES
  $ bitsocial page-sort ls

EXAMPLES
  $ bitsocial page-sort list

  $ bitsocial page-sort list -q

bitsocial page-sort remove NAME

Remove an installed page sort package. Refuses while a community's settings.pages still names it, unless --force is passed

USAGE
  $ bitsocial page-sort remove NAME --pkcRpcUrl <value> [--pkcOptions.dataPath <value>] [--force]

ARGUMENTS
  NAME  The page sort package name (e.g., my-page-sort or @scope/my-page-sort)

FLAGS
  --force                        Remove without checking whether communities still use it (the daemon is not contacted
                                 for the check)
  --pkcOptions.dataPath=<value>  Data path where page sorts are installed
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Remove an installed page sort package. Refuses while a community's settings.pages still names it, unless --force is
  passed

ALIASES
  $ bitsocial page-sort uninstall
  $ bitsocial page-sort rm
  $ bitsocial page-sort un

EXAMPLES
  $ bitsocial page-sort remove @pkcprotocol/active-page-sort

  $ bitsocial page-sort remove @pkcprotocol/active-page-sort --force

See code: src/cli/commands/page-sort/remove.ts

bitsocial page-sort rm NAME

Remove an installed page sort package. Refuses while a community's settings.pages still names it, unless --force is passed

USAGE
  $ bitsocial page-sort rm NAME --pkcRpcUrl <value> [--pkcOptions.dataPath <value>] [--force]

ARGUMENTS
  NAME  The page sort package name (e.g., my-page-sort or @scope/my-page-sort)

FLAGS
  --force                        Remove without checking whether communities still use it (the daemon is not contacted
                                 for the check)
  --pkcOptions.dataPath=<value>  Data path where page sorts are installed
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Remove an installed page sort package. Refuses while a community's settings.pages still names it, unless --force is
  passed

ALIASES
  $ bitsocial page-sort uninstall
  $ bitsocial page-sort rm
  $ bitsocial page-sort un

EXAMPLES
  $ bitsocial page-sort remove @pkcprotocol/active-page-sort

  $ bitsocial page-sort remove @pkcprotocol/active-page-sort --force

bitsocial page-sort un NAME

Remove an installed page sort package. Refuses while a community's settings.pages still names it, unless --force is passed

USAGE
  $ bitsocial page-sort un NAME --pkcRpcUrl <value> [--pkcOptions.dataPath <value>] [--force]

ARGUMENTS
  NAME  The page sort package name (e.g., my-page-sort or @scope/my-page-sort)

FLAGS
  --force                        Remove without checking whether communities still use it (the daemon is not contacted
                                 for the check)
  --pkcOptions.dataPath=<value>  Data path where page sorts are installed
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Remove an installed page sort package. Refuses while a community's settings.pages still names it, unless --force is
  passed

ALIASES
  $ bitsocial page-sort uninstall
  $ bitsocial page-sort rm
  $ bitsocial page-sort un

EXAMPLES
  $ bitsocial page-sort remove @pkcprotocol/active-page-sort

  $ bitsocial page-sort remove @pkcprotocol/active-page-sort --force

bitsocial page-sort uninstall NAME

Remove an installed page sort package. Refuses while a community's settings.pages still names it, unless --force is passed

USAGE
  $ bitsocial page-sort uninstall NAME --pkcRpcUrl <value> [--pkcOptions.dataPath <value>] [--force]

ARGUMENTS
  NAME  The page sort package name (e.g., my-page-sort or @scope/my-page-sort)

FLAGS
  --force                        Remove without checking whether communities still use it (the daemon is not contacted
                                 for the check)
  --pkcOptions.dataPath=<value>  Data path where page sorts are installed
  --pkcRpcUrl=<value>            (required) [default: ws://localhost:9138/] URL to PKC RPC

DESCRIPTION
  Remove an installed page sort package. Refuses while a community's settings.pages still names it, unless --force is
  passed

ALIASES
  $ bitsocial page-sort uninstall
  $ bitsocial page-sort rm
  $ bitsocial page-sort un

EXAMPLES
  $ bitsocial page-sort remove @pkcprotocol/active-page-sort

  $ bitsocial page-sort remove @pkcprotocol/active-page-sort --force

bitsocial reachability disable

Stop serving browsers and restore the kubo config. State is kept, so enable does not need new certificates

USAGE
  $ bitsocial reachability disable [--pkcOptions.dataPath <value>] [--purge]

FLAGS
  --pkcOptions.dataPath=<value>  Data path of the node
  --purge                        Also move the state directory, including the ACME account and certificates, to a
                                 timestamped backup

DESCRIPTION
  Stop serving browsers and restore the kubo config. State is kept, so `enable` does not need new certificates

EXAMPLES
  $ bitsocial reachability disable

  $ bitsocial reachability disable --purge

See code: src/cli/commands/reachability/disable.ts

bitsocial reachability enable

Turn reachability back on: re-run discovery and repair from the stored choices, without asking anything

USAGE
  $ bitsocial reachability enable [--pkcOptions.dataPath <value>]

FLAGS
  --pkcOptions.dataPath=<value>  Data path of the node

DESCRIPTION
  Turn reachability back on: re-run discovery and repair from the stored choices, without asking anything

EXAMPLES
  $ bitsocial reachability enable

See code: src/cli/commands/reachability/enable.ts

bitsocial reachability setup

Make this node dialable from browsers: discover public addresses, obtain a certificate, configure kubo and verify. Safe to rerun

USAGE
  $ bitsocial reachability setup [--pkcOptions.dataPath <value>] [--domain <value>] [--announce <value>] [--force]
    [--staging] [--non-interactive]

FLAGS
  --announce=<value>             A multiaddr your own proxy serves, e.g. /dns4/node.example/tcp/443/tls/ws. Announced
                                 only after a real libp2p dial succeeds
  --domain=<value>               A domain pointing at this machine, to get a certificate for or to forward through your
                                 own proxy
  --force                        Continue when the domain does not resolve to this machine, for proxies in front of it
  --non-interactive              Never ask. Exit non-zero with the reason if an answer would be needed
  --pkcOptions.dataPath=<value>  Data path of the node
  --staging                      Use the Let's Encrypt staging CA. Its certificates are not trusted by browsers

DESCRIPTION
  Make this node dialable from browsers: discover public addresses, obtain a certificate, configure kubo and verify.
  Safe to rerun

EXAMPLES
  $ bitsocial reachability setup

  $ bitsocial reachability setup --staging

  $ bitsocial reachability setup --domain node.example

  $ bitsocial reachability setup --domain node.example --announce /dns4/node.example/tcp/443/tls/ws

  $ bitsocial reachability setup --non-interactive

See code: src/cli/commands/reachability/setup.ts

bitsocial reachability status

Show whether browsers can reach this node: mode, announced addresses, certificate expiry, last checks, and whether each requirement is met, including permission to bind UDP 443

USAGE
  $ bitsocial reachability status [--json] [--pkcOptions.dataPath <value>]

FLAGS
  --pkcOptions.dataPath=<value>  Data path of the node

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Show whether browsers can reach this node: mode, announced addresses, certificate expiry, last checks, and whether
  each requirement is met, including permission to bind UDP 443

EXAMPLES
  $ bitsocial reachability status

  $ bitsocial reachability status --json

See code: src/cli/commands/reachability/status.ts

bitsocial update check

Check if a newer version of bitsocial is available on npm

USAGE
  $ bitsocial update check

DESCRIPTION
  Check if a newer version of bitsocial is available on npm

EXAMPLES
  $ bitsocial update check

See code: src/cli/commands/update/check.ts

bitsocial update install [VERSION]

Install a specific version of bitsocial from npm

USAGE
  $ bitsocial update install [VERSION] [--force] [--restart-daemons]

ARGUMENTS
  [VERSION]  [default: latest] Version to install (e.g. "0.19.40" or "latest")

FLAGS
  --force                 Reinstall even if already on the requested version
  --[no-]restart-daemons  Stop all running daemons, update, and restart them with the same settings

DESCRIPTION
  Install a specific version of bitsocial from npm

EXAMPLES
  $ bitsocial update install

  $ bitsocial update install latest

  $ bitsocial update install 0.19.40

  $ bitsocial update install --force

  $ bitsocial update install --no-restart-daemons

See code: src/cli/commands/update/install.ts

bitsocial update versions

List available bitsocial versions on npm

USAGE
  $ bitsocial update versions [--limit <value>]

FLAGS
  --limit=<value>  [default: 20] Maximum number of versions to display

DESCRIPTION
  List available bitsocial versions on npm

EXAMPLES
  $ bitsocial update versions

  $ bitsocial update versions --limit 5

See code: src/cli/commands/update/versions.ts

Contribution

We're always happy to receive pull requests. Few things to keep in mind:

• This repo follows Angular commit conventions. Easiest way to follow these conventions is by using npm run commit instead of git commit
• If you're adding a feature, make sure to add tests to your pull requests

Feedback

We would love your feedback on our community channels