@bitsocial/bitsocial-cli

v0.19.73

Published

8 days ago

Command line interface to Bitsocial API

0High
0Medium
0Low

tomcasaburi

rinse12

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

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 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

| Path | Description | |---|---| | /data/bitsocial | Bitsocial data directory | | /data/bitsocial/communities | Community SQLite databases | | /data/bitsocial/.bitsocial-cli.ipfs | Kubo IPFS repository | | /logs/bitsocial | Log files |

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.

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`

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

USAGE
  $ bitsocial challenge add PACKAGE [--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

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 [--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

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 [--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

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

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

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

FLAGS
  --pkcOptions.dataPath=<value>  Data path where challenges are installed

DESCRIPTION
  Remove an installed challenge package

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

EXAMPLES
  $ bitsocial challenge remove my-challenge

  $ bitsocial challenge remove @scope/my-challenge

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

`bitsocial challenge rm NAME`

Remove an installed challenge package

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

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

FLAGS
  --pkcOptions.dataPath=<value>  Data path where challenges are installed

DESCRIPTION
  Remove an installed challenge package

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

EXAMPLES
  $ bitsocial challenge remove my-challenge

  $ bitsocial challenge remove @scope/my-challenge

`bitsocial challenge un NAME`

Remove an installed challenge package

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

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

FLAGS
  --pkcOptions.dataPath=<value>  Data path where challenges are installed

DESCRIPTION
  Remove an installed challenge package

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

EXAMPLES
  $ bitsocial challenge remove my-challenge

  $ bitsocial challenge remove @scope/my-challenge

`bitsocial challenge uninstall NAME`

Remove an installed challenge package

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

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

FLAGS
  --pkcOptions.dataPath=<value>  Data path where challenges are installed

DESCRIPTION
  Remove an installed challenge package

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

EXAMPLES
  $ bitsocial challenge remove my-challenge

  $ bitsocial challenge remove @scope/my-challenge

`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/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 an
  image captcha

    $ 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 captcha-canvas-v3

  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 (much faster: skips the per-community 'started' lookup)
      --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>...]
    [--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.c
                                  om,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.
  --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}/.ipfs-bitsocial-cli/config 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 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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

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

Table of contents

What is Bitsocial?

What is bitsocial-cli?

Install

Build from source (optional)

Docker

Data paths inside the container

Docker Compose (recommended)

Viewing logs

Example docker-compose.yml

Docker Run

Building the Docker image locally

Usage

The data/config directory of Bitsocial

The logs directory of Bitsocial

Running Daemon

Creating your first community

Listing all your communities

Adding a role moderator to your community

Adding a role owner to your community

Adding a role admin to your community

Removing a role

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 update check

bitsocial update install [VERSION]

bitsocial update versions

Contribution

Feedback

`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 update check`

`bitsocial update install [VERSION]`

`bitsocial update versions`