Command line tool to manage Earthstar sqlite databases

Usage no npm install needed!

<script type="module">
  import earthstarCli from '';


Earthstar command-line tool

Lets you inspect, modify and sync Earthstar workspaces as sqlite files on your local disk. Each sqlite file holds exactly one workspace.

You can learn more about workspaces and other Earthstar concepts in the docs.


npm install --global earthstar-cli

Note that this installs a command called just earthstar, not earthstar-cli.


Let's make a new workspace called +demo.123456. Workspaces have this format:


WORKSPACE_NAME: 1 to 15 lower-case letters
RANDOM_CHARS: 1 to 44 upper- or lower-case letters or numbers

Make a new database file that will hold the +demo.123456 workspace. All the other commands expect a database to already exist -- you have to create one first.

earthstar create-database demo.sqlite +demo.123456

Create an author identity starting with suzy. The name must be 4 lowercase letters. We'll save it in a JSON file.

earthstar generate-author suzy > author-keypair.json

cat author-keypair.json
    "address": "@suzy.BvWCCQJfGVNQ1q1VFATBvAwfX4N8bQXWXxvFsViLa85P",
    "secret": "3P1BisPyTs2EGMSHpXKHLbeoZewrYePfETbf19gi8E6z"

Save a value at a path, thus creating a document. We'll use the author identity we just created.

earthstar set demo.sqlite author-keypair.json /test/path "Test value"

Print out the documents in a workspace

earthstar pairs demo.sqlite
    Test value

earthstar documents demo.sqlite
    "format": "es.3",
    "workspace": "+demo.123456",
    "path": "/test/path",
    "value": "Test value",
    "author": "@suzy.BvWCCQJfGVNQ1q1VFATBvAwfX4N8bQXWXxvFsViLa85P",
    "timestamp": 1592936759163000,
    "signature": (... redacted for length ...)

Sync two sqlite files with each other. Both must already exist and have the same workspace.

# make another database to sync with
earthstar create-workspace demo2.sqlite +demo.123456

# sync
earthstar sync demo.sqlite demo2.sqlite

# print the contents of the second one to verify it worked
earthstar pairs demo2.sqlite

Sync with an earthstar-pub server on the internet. (This example server might take a moment to start up if it hasn't been used for a while)

earthstar sync demo.sqlite

Now visit to see your data on the server. (Pub servers exist to help with syncing, not to publish things to the internet, but for this demo you can view the content through the web.)



  • <dbFilename>: filename to an sqlite file
  • <workspaceAddress>: a workspace address like +gardening.ac9eEIhf9332He0afwf
  • <authorFile>: a JSON file in the format printed by generate-author containing an author's private key
  • <path>: an Earthstar path, starting with a slash
  • <value>: any string
  • <url>: HTTP address of an earthstar pub.
Usage: earthstar [options] [command]

  -h, --help                                        display help for command

  generate-author <shortname>                       Generate and print a new author keypair
                                                    with the given 4-letter shortname
  create-workspace <dbFilename> <workspaceAddress>  Create a new sqlite database file to hold
                                                    a given workspace
  info <dbFilename>                                 Report basic info about the workspace
  pairs <dbFilename>                                Show paths and values
  paths <dbFilename>                                List the paths
  documents <dbFilename>                            List the documents in a workspace
                                                    including history documents
  values <dbFilename>                               List the values in a workspace (sorted by
                                                    their path)
  authors <dbFilename>                              List the authors in a workspace
  set <dbFilename> <authorFile> <key> <value>       Set a value at a path.  authorFile should
                                                    be a JSON file holding a keypair.
  sync <dbOrUrl1> <dbOrUrl2>                        Sync between two local files and/or
                                                    remote servers.
  help [command]                                    display help for command