Add sbot/ssb-server CLI guides from ssbc/docs repo

SUMMARY.md

@@ -34,8 +34,23 @@
     - [Scalable Secure Scuttlebutt paper](https://github.com/dominictarr/scalable-secure-scuttlebutt/blob/master/paper.md)
     - [Secret Handshake paper](http://dominictarr.github.io/secret-handshake-paper/shs.pdf)
 * [Guides](guides/index.md)
+  - [Command Line Client](guides/cli-first-steps.md)
+    - [Install](guides/ssb-server/install.md)
+    - [Tutorial](guides/ssb-server/tutorial.md)
+    - [Create a Javascript client](guides/ssb-server/create-a-js-client.md)
+    - [Get your address](guides/ssb-server/get-your-address.md)
+    - [Get your ID](guides/ssb-server/get-your-id.md)
+    - [Update your profile](guides/ssb-server/update-your-profile.md)
+    - [Follow and unfollow](guides/ssb-server/follow-unfollow.md)
+    - [Use an invite](guides/ssb-server/use-an-invite.md)
+    - [Publish a file](guides/ssb-server/publish-a-file.md)
+    - [Publish a post](guides/ssb-server/publish-a-post.md)
+    - [Publish encrypted messages](guides/ssb-server/publish-encrypted-messages.md)
+  - [Scuttlebutt Pubs](guides/ssb-server/setup-a-pub.md)
+    - [Setup Pub](guides/ssb-server/setup-a-pub.md)
+    - [Announce a Pub](guides/ssb-server/announce-a-pub-server.md)
+    - [Create an invite](guides/ssb-server/create-an-invite.md)
   - [Scuttlebutt Guide](https://github.com/ssbc/scuttlebutt-guide)
-  - [First steps with sbot](guides/cli-first-steps.md)
   - [SSB field guide](https://github.com/nichoth/ssb-field-guide)
   - [Introduction to SSB: Your Test Playground](https://josiahwitt.com/2018/07/08/scuttlebutt-intro-test-playground.html)
   - [Introduction to SSB: Flume & Plugins](https://josiahwitt.com/2018/07/08/scuttlebutt-intro-flume.html)

guides/cli-first-steps.md

@@ -1,42 +1,42 @@
-# First steps with sbot, a command line tool for Scuttlebutt
+# First steps with ssb-server, a command line tool for Scuttlebutt
 
-I'm new to Scuttlebutt and Patchwork, and writing this as I start to explore its possibilities with the sbot command line tool. Feel free to respond with any suggestions or questions. My interest in Scuttlebutt was piqued by [@andrestaltz](@QlCTpvY7p9ty2yOFrv1WU1AE88aoQc4Y7wYal7PFc+w=.ed25519)'s post, [An Off-Grid Social Network](https://staltz.com/an-off-grid-social-network.html), especially how the decentralized, peer-to-peer architecture works to support offline use and avoids reliance on any servers with special authority.
+I'm new to Scuttlebutt and Patchwork, and writing this as I start to explore its possibilities with the `ssb-server` command line tool. Feel free to respond with any suggestions or questions. My interest in Scuttlebutt was piqued by [@andrestaltz](@QlCTpvY7p9ty2yOFrv1WU1AE88aoQc4Y7wYal7PFc+w=.ed25519)'s post, [An Off-Grid Social Network](https://staltz.com/an-off-grid-social-network.html), especially how the decentralized, peer-to-peer architecture works to support offline use and avoids reliance on any servers with special authority.
 
 Scuttlebutt applications depend on a *server* component that maintains the connection with the Scuttlebutt network. Many Scuttlebutt applications, including Patchwork, use [ssb-server](https://github.com/ssbc/ssb-server) to interact with the Scuttlebutt network. The first time you run ssb-server (or an application using it), an identity is created (in the form of a public and private key pair) and this identity is shared by all applications that communicate via ssb-server.
 
-**sbot** is a command line tool included with ssb-server. To install it, install the *ssb-server* Node.js package globally by running:
+`ssb-server` is a command line tool included with ssb-server. To install it, install the *ssb-server* Node.js package globally by running:
 
-```
+```bash
 npm install --global ssb-server
 ```
 
-This should let you run *sbot* on the command line. Let's start by using **whoami** to verify that sbot can connect to a Scuttlebot server and has the right identity.
+This should let you run `ssb-server` on the command line. Let's start by using the `whoami` sub-command to verify that command line client can connect to a server and has the right identity.
 
-If you are connected to the Scuttlebutt network, this command should return a user ID. For example, this shows running *sbot whoami* and it returning my user ID:
+If you are connected to the Scuttlebutt network, this command should return a user ID. For example, this shows running `ssb-server whoami` and it returning my user ID:
 
-```
-$ sbot whoami
+```bash
+ssb-server whoami
 {
   "id": "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25519"
 }
 ```
 
 If you are not connected to the network, you will see an error message like this:
 
-```
-$ sbot whoami
+```bash
+ssb-server whoami
 Error: Could not connect to the scuttlebot server.
 Use the "server" command to start it.
 ```
 
-To connect to the network, you can either start Patchwork or another application that uses Scuttlebot, or run *sbot server*, which starts the server component.
+To connect to the network, you can either start Patchwork or another application that uses Scuttlebot, or run *ssb-server start*, which starts the server component.
 
 On the Scuttlebutt network, each user has a *feed* or *log* made up of messages signed by the user. Only the user can write to their feed, since only the user should possess the identity's private key and be able to sign messages with it. Users interact with each other by publishing messages on their own feed that mention users, establish a *follow* link with another user, or link to the message of another user.
 
-Let's use the **latestSequence** command to find how many items are in my feed. For example, this shows running *sbot latestSequence* with one argument (my user ID) and it returning the last sequence number in my feed and the timestamp of this item:
+Let's use the `latestSequence` sub-command to find how many items are in my feed. For example, this shows running `ssb-server latestSequence` with one argument (my user ID) and it returning the last sequence number in my feed and the timestamp of this item:
 
-```
-$ sbot latestSequence "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25519"
+```bash
+ssb-server latestSequence "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25519"
 {
   "sequence": 24,
   "ts": 1491624622201
@@ -45,17 +45,17 @@ $ sbot latestSequence "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25519"
 
 Using JavaScript, I can convert this timestamp into a localized date to verify that this was the date and time of my last message:
 
-```
-$ echo "console.log(new Date(1491624622201).toLocaleString());" | node
+```bash
+echo "console.log(new Date(1491624622201).toLocaleString());" | node
 4/7/2017, 11:10:22 PM
 ```
 
-Next, let's use the **createUserStream** command to retrieve items from my feed. This command has many options, including a mode to perform a full retrieval of the feed and a *live* mode where messages appear in real-time as they arrive.
+Next, let's use the `createUserStream` sub-command to retrieve items from my feed. This command has many options, including a mode to perform a full retrieval of the feed and a *live* mode where messages appear in real-time as they arrive.
 
 With the *limit* argument, we can retrieve the first item from my feed. For example:
 
-```
-$ sbot createUserStream --id "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25519" --limit 1
+```bash
+ssb-server createUserStream --id "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25519" --limit 1
 {
   "key": "%S/nfXzDK3waYEaEDwwGA7FsIqFzpIiU3200Lf0aG/Ps=.sha256",
   "value": {
@@ -76,10 +76,10 @@ $ sbot createUserStream --id "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25
 
 Notice that the *sequence* value is 1 and the *previous* value is null. Also, this is an *about* type message made with Patchwork that identifies my user ID with the name *arithmetric*.
 
-By adding the *reverse* argument to the *sbot createUserStream* command, we can retrieve the last item from my feed. For example:
+By adding the *reverse* argument to the *ssb-server createUserStream* command, we can retrieve the last item from my feed. For example:
 
-```
-$ sbot createUserStream --id "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25519" --limit 1 --reverse
+```bash
+ssb-server createUserStream --id "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25519" --limit 1 --reverse
 {
   "key": "%hl3+i0yaWRo2DG11VdpQhXx/ol2lbf73W9rdHbiaV5c=.sha256",
   "value": {
@@ -100,10 +100,10 @@ $ sbot createUserStream --id "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25
 
 This message has a *sequence* value of 24, which matches the last sequence number from the *latestSequence* command above. This message is the *contact* type with *following* set to true, so it is the message recording my action to follow the user in the *contact* field.
 
-Now, let's use the **get** command to get the message previous to the last one. The *sbot get* command accepts one argument, the message ID. For example, this shows running get with the message ID in the previous field above and the message response:
+Now, let's use the `get` sub-command to get the message previous to the last one. The *ssb-server get* command accepts one argument, the message ID. For example, this shows running get with the message ID in the previous field above and the message response:
 
-```
-$ sbot get "%rQ6UTukySj3b3igS0M4FTBB/H/VmM3U8Z6gwtp3v4iY=.sha256"
+```bash
+ssb-server get "%rQ6UTukySj3b3igS0M4FTBB/H/VmM3U8Z6gwtp3v4iY=.sha256"
 {
   "previous": "%jhaGHJiDINuSp1gr6nHbxhB9BCW9HIPtGR3ntdN3EWM=.sha256",
   "author": "@btxEYD1gibOZZKbtxJFTQ2m560U3zIgbZ2vII93WCIk=.ed25519",
@@ -115,10 +115,10 @@ $ sbot get "%rQ6UTukySj3b3igS0M4FTBB/H/VmM3U8Z6gwtp3v4iY=.sha256"
 }
 ```
 
-Notice that the content value is not a JSON object. This is an example of an encrypted private message. Since this private message is in my feed, I can decrypt it with the **private.unbox** command. For example, this shows running this command with the encrypted value and receiving the decrypted JSON message content:
+Notice that the content value is not a JSON object. This is an example of an encrypted private message. Since this private message is in my feed, I can decrypt it with the `private.unbox` sub-command. For example, this shows running this command with the encrypted value and receiving the decrypted JSON message content:
 
-```
-$ sbot private.unbox "cZOlfY2YQBM..."
+```bash
+ssb-server private.unbox "cZOlfY2YQBM..."
 {
   "type": "post",
   "text": "hello world! this is a test encrypted message",
@@ -129,4 +129,4 @@ $ sbot private.unbox "cZOlfY2YQBM..."
 }
 ```
 
-That's just a brief introduction to the Scuttlebutt network using the sbot command line tool. For more information, check out the [API/CLI reference](https://ssbc.github.io/ssb-server/api.html) and the [Secure Scuttlebutt](https://ssbc.github.io/ssb-db/) protocol overview.
+That's just a brief introduction to the Scuttlebutt network using the `ssb-server` command line tool. For more information, check out the [API/CLI reference](https://ssbc.github.io/ssb-server/api.html) and the [Secure Scuttlebutt](https://ssbc.github.io/ssb-db/) protocol overview.

guides/ssb-server/announce-a-pub-server.md

@@ -0,0 +1,12 @@
+# Announce a Pub Server
+
+To announce a pub server, publish this `pub` message:
+
+```bash
+ssb-server publish --type pub --pub.link {feedId} --pub.host {string} --pub.port {number}
+```
+```js
+sbot.publish({ type: 'pub', pub: { link: feedId, host: string, port: number } }, cb)
+```
+
+Scuttlebot, and any user that follows you, will add the pub to their peer list, and begin contacting it for syncing.

guides/ssb-server/create-a-js-client.md

@@ -0,0 +1,11 @@
+# Create a JS Client
+
+The current process for connecting to Scuttlebot involves loading the master keypair from sbot's config (`~/.ssb/secret`).
+Do this automatically with the [ssb-client](https://github.com/ssbc/ssb-client) module.
+
+```js
+var ssbClient = require('ssb-client')
+ssbClient(function (err, sbot) {
+  // ready
+})
+```

guides/ssb-server/create-an-invite.md

@@ -0,0 +1,12 @@
+# Create an Invite
+
+If you're operating a Pub, you'll need to create invites for new members to join it.
+
+The command to create an invite code is:
+
+```bash
+ssb-server invite.create {num-uses}
+```
+
+Where `{num-uses}` is the number of times the invite can be used before expiring.
+The recommended default is 1.

guides/ssb-server/follow-unfollow.md

@@ -0,0 +1,21 @@
+# Follow / Unfollow
+
+To follow a users feed, publish this `contact` message:
+
+```bash
+ssb-server publish --type contact --contact {feedId} --following
+```
+```js
+sbot.publish({ type: 'contact', contact: feedId, following: true }, cb)
+```
+
+Scuttlebot will query peers for new messages from this feed.
+
+To stop following a user, publish this `contact` message:
+
+```bash
+ssb-server publish --type contact --contact {feedId} --no-following
+```
+```js
+sbot.publish({ type: 'contact', contact: feedId, following: false }, cb)
+```

guides/ssb-server/get-your-address.md

@@ -0,0 +1,14 @@
+# Get your Address
+
+To get your address:
+
+```bash
+ssb-server getAddress
+```
+```js
+sbot.getAddress(cb)
+```
+
+Addresses look like `ip:port:id`.
+This will try to get your public address.
+If you don't have a public IP, this will probably give an IP in the 192 range.

guides/ssb-server/get-your-id.md

@@ -0,0 +1,12 @@
+# Get your ID
+
+To get your ID:
+
+```bash
+ssb-server whoami
+```
+```js
+sbot.whoami(cb)
+```
+
+Incidentally, your ID is your public key.

guides/ssb-server/howto-use-an-invite.md

@@ -0,0 +1,15 @@
+# Use an Invite
+
+If you want to connect to your friends across the net, you need to be followed by a Pub server.
+
+First get an invite-code from a Pub operator you know, or [setup your own pub](howto-setup-a-pub).
+
+If you're using Patchwork, you can use the UI to use the code.
+However, if you want to use Scuttlebot, you can use the following command:
+
+```bash
+ssb-server invite.accept {code}
+```
+
+Your Scuttlebot will now connect to, and sync with, the Pub.
+Other users can sync with the pub to receive your log.

guides/ssb-server/install.md

@@ -0,0 +1,95 @@
+# Install Scuttlebot
+
+## From NPM
+
+NPM hosts the stable release.
+It will be the least likely to have bugs.
+
+**Dependencies:**
+
+ - node v4 and greater (you might like to use [nvm](https://github.com/creationix/nvm))
+ - node-gyp (```npm install -g node-gyp```)
+
+***Linux Dependencies***
+Installation may fail when building the libsodium dependencies due to missing aclocal. On Ubuntu you will need to run:
+
+```bash
+sudo apt-get install autotools-dev automake
+```
+
+**Install:**
+
+```bash
+npm install ssb-server -g
+```
+
+**Run:**
+
+Start scuttlebutt server.
+
+```bash
+ssb-server start
+```
+
+Then, in another session, use the cli tool to access the API:
+
+```bash
+ssb-server whoami
+ssb-server publish --type post --text "Hello, world"
+ssb-server log
+```
+
+You can get help with `-h`.
+
+
+## From Git
+
+GitHub hosts the development version.
+It will contain updates not yet published on NPM.
+
+**Dependencies:**
+
+ - node v4 and greater (you might like to use [nvm](https://github.com/creationix/nvm))
+ - node-gyp (```npm install -g node-gyp```)
+
+***Linux Dependencies***
+Installation may fail when building the libsodium dependencies due to missing aclocal. On Ubuntu you will need to run:
+
+```bash
+sudo apt-get install autotools-dev automake
+```
+
+**Install:**
+
+```bash
+git clone https://github.com/ssbc/ssb-server.git
+cd scuttlebot
+npm install
+```
+
+**Run:**
+
+From directory you cloned scuttlebot to:
+
+```bash
+./bin.js server
+```
+
+Then, in another session, use the cli tool to access the API:
+
+```bash
+./bin.js whoami
+./bin.js publish --type post --text "Hello, world"
+./bin.js log
+```
+
+You can get help with `-h`.
+
+**Update:**
+
+From directory you cloned scuttlebot to:
+
+```bash
+git pull origin master
+npm install
+```