Distributed Press CLI

A Command Line Interface (CLI) for interacting with the Distributed Press API and Social Inbox. Manage your sites, register your ActivityPub actor, and engage with followers seamlessly from the command line.

Table of Contents

• Installation
  • Node.js and npm Setup
• Distributed Press Setup
  • Register as Publisher (Trial Account)
  • Set Your Authentication Token
  • Create Your Site
  • Publish Your Site
  • DNS Setup
  • Clone an Existing Site
• Social Inbox Setup
  • Use Staticpub Template
  • Generate a Keypair
  • Register Your Actor
  • Send a Post to Followers
  • Patch a Site
• Configuration
• Commands
• License
• Resources

Installation

Node.js and npm Setup

To use dp-cli, you’ll need Node.js and npm. Please refer to the Node.js official documentation to install Node.js. Once installed, npm (Node Package Manager) will be available, allowing you to run commands like npx and npm.

• npm: Comes bundled with Node.js. Verify installation by running:

  node -v
  npm -v

For additional help with npm commands, see the npm documentation.

Using npx

You can use dp-cli without installation by running:

npx dp-cli <command>

Global Installation with npm

To install dp-cli globally, use:

npm install -g dp-cli

Once installed, you can use dp-cli from anywhere in your terminal.

Distributed Press Setup (Publish Website)

Register as Publisher

Register a trial publisher account on Distributed Press using your email:

dp-cli register

You will be prompted for your name and email. Note: currently, only one site per email is allowed.

OR Set Your Authentication Token Manually

Obtain your authToken from your Distributed Press API administrator and set it using:

dp-cli set-auth-token

You will be prompted to enter your authentication token.

Create Your Site

Once registered, create a new site by specifying the domain name and whether it should be public:

dp-cli create-site

Publish Your Site

To upload and publish static content to the DP site from a specified directory:

dp-cli publish ./folder_here

DNS Setup

To use a custom domain for your Distributed Press site, you'll need to set up a DNS record to point to the Distributed Press infrastructure.

Using Distributed Press Infrastructure

• If you wish to use the official Distributed Press instance for your HTTPS traffic, contact the Distributed Press team.
• Alternatively, refer to the documentation for self-hosting for guidance on running your own infrastructure.

CNAME Record

| Type | Name | Value | | ----- | ------------- | ------------------------ | | CNAME | <your-site> | api.distributed.press. |

• Replace `your-site`` with your domain or subdomain name.
• Ensure that the trailing dot . is included in api.distributed.press. as required.

_dnslink Record

To make your site accessible through Distributed Press, set an NS Record to delegate DNSLink lookups to Distributed Press.

| Type | Name | Value | | ---- | ---------------------- | ---------------------------------- | | NS | _dnslink.your.domain | api.distributed.press. |

• This eliminates the need to manually set TXT records.
• contact the Distributed Press team for assistance if needed.

Example

If your site links include:

"ipfs": {
  "dnslink": "/ipns/k51qzi5uqu5djj6yo1nne5r2oomxgroy3tezhgupvx0v2jlbighfah1k028sc1/"
},
"hyper": {
  "dnslink": "/hyper/t685fd3snbadhqkss8spcgz454p95ap77kdfjafotsxfhhrhuqio/"
}

You only need to configure the NS Record as shown above. DNSLink propagation will handle IPFS and Hyper links automatically.

After DNS propagation, users will be able to access the site at example.com over IPFS and Hyper.

• ipns://example.com
• hyper://example.com

SSL Requirements

To use your custom domain, ensure that your domain has a valid HTTPS certificate. Most DNS providers offer free certificate generation via Let's Encrypt or similar services.

Clone an Existing Site

Clone a website by creating a static copy from its HTTP URL:

dp-cli clone <site-id>

Social Inbox Setup (Send Posts to Fediverse)

Use Staticpub Template

1. Fork the Repository: Visit the staticpub.distributed.press repository on GitHub and click the "Fork" button to create your own copy.

2. Clone Your Fork:

git clone https://github.com/hyphacoop/staticpub.distributed.press.git
cd staticpub.distributed.press

3. Replace Domain, Username, and Name:

For Linux Users:

find . -type f -exec sed -i 's/staticpub\.distributed\.press/yourdomain\.com/g; s/dp/username/g; s/"Distributed Press"/"Your Name"/g' {} +

For macOS Users:

find . -type f -exec sed -i '' 's/staticpub\.distributed\.press/yourdomain\.com/g; s/dp/username/g; s/"Distributed Press"/"Your Name"/g' {} +

This will replace:

• staticpub.distributed.press → yourdomain.com
• dp → yourusername
• Distributed Press → Your Name

Make sure to update the publicKeyPem field in the following files with your actual public key from the .dprc configuration file:

• about.jsonld
• about-ipns.jsonld

How to Find Your Public Key:

1. Open your .dprc file (generated during setup).
2. Copy the value of "publicKeyPem" (including the BEGIN and END lines).
3. Paste it into the publicKeyPem field in the JSON files mentioned above.

Example:

    "publicKey": {
      "@context": "https://w3id.org/security/v1",
      "@type": "Key",
      "id": "https://staticpub.distributed.press/about.jsonld#main-key",
      "owner": "https://staticpub.distributed.press/about.jsonld",
      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nYOUR_PUBLIC_KEY_HERE\n-----END PUBLIC KEY-----\n"
    }

Replace YOUR_PUBLIC_KEY_HERE with your actual public key from .dprc.

For using the Social Inbox, you need to generate a keypair and register your ActivityPub actor.

Generate a Keypair

Run the following command to generate a new RSA keypair:

dp-cli generate-keypair

Purpose:
This keypair is used for authenticating your interactions with the Social Inbox and the fediverse at large, ensuring secure communication and verifying your identity.

Note:
If you only plan to use the DP API for static file publishing, generating a keypair might not be necessary. However, it's recommended for enhanced security and functionality when interacting with the Social Inbox.

This will generate a keypair and save it to your .dprc configuration file.

⚠️ Publish the Staticpub Template

Make sure your site is published before registering an actor and sending a post, as this is a prerequisite for proper functionality and includes your public key for signing.

Please follow the steps from this section:

• Distributed Press Setup

Additionally, ensure that the WebFinger /.well-known file is correctly published for your domain. To automate this process, you can set up GitHub Actions in the workflows directory.

Alternatively, you can use the staticpub's publish.yml. Be sure to update the site_url and add your secret DISTRIBUTED_PRESS_TOKEN in the workflow configuration.

Register Your Actor

Register your ActivityPub actor with the Social Inbox:

dp-cli register-actor

This will register your actor with the Social Inbox and save the details to your configuration.

Send a Post to Followers

Published the template? Now, let's send a post to your followers:

dp-cli send-post ./path_to_activity.json

Example (as per the staticpub template):

dp-cli send-post ./posts/helloworld.jsonld

Patch a Site

After publishing your site and registering your actor, you might need to update your site with new content or activities. Use the patch command to add the note/activity JSON and update the outbox with the new activity.

dp-cli patch -i <site-id> ./path_to_patch_folder

Configuration

The CLI uses a configuration file named .dprc to store API URLs, authentication tokens, keypairs, and actor information. The configuration file follows the format expected by the rc module, which loads configuration options in a flexible way.

Your .dprc file should look like this:

{
  "dpApiUrl": "https://api.distributed.press/v1",
  "socialInboxUrl": "https://social.distributed.press/v1",
  "authToken": "<your-auth-token>",
  "keypair": {
    "publicKeyPem": "<your-public-key>",
    "privateKeyPem": "<your-private-key>"
  },
  "domain": "<your-site-domain>",
  "actorUsername": "<your-actor-username>",
  "actorUrl": "<your-actor-url>",
  "publicKeyId": "<your-public-key-id>"
}

• dpApiUrl: The base URL for the Distributed Press API.
• socialInboxUrl: The base URL for the Social Inbox.
• authToken: Your authentication token for API access.
• keypair: Your public and private keys for secure interactions.
• domain: Your custom domain for the site, e.g., example.com.
• actorUsername: Your ActivityPub actor username.
• actorUrl: The URL of your actor.
• publicKeyId: The ID of your public key.

Ensure that your .dprc file is not committed to version control to keep your credentials secure.

Commands

register

Description:

Register a trial publisher account with Distributed Press:

Usage:

dp-cli register

set-auth-token

Description:
Set your authentication token for API access.

Usage:

dp-cli set-auth-token

Prompt:

• Enter your authentication token.

create-site

Description:

Create a new site by specifying the domain name and whether it should be public

Usage:

dp-cli create-site

Prompt:

• Enter your site domain: e.g., example.com
• Is your site public? (Yes/No)

publish-site

Description:

Upload and publish static content to the DP site from a specified directory:

Usage:

dp-cli publish ./folder_here

clone

Description:

Clone a website by creating a static copy from its HTTP URL:

Usage:

dp-cli clone <site-id>

generate-keypair

Description:
Generate a new RSA keypair and save it to your configuration.

Usage:

dp-cli generate-keypair

register-actor

Description:
Register your ActivityPub actor with the Social Inbox.

Usage:

dp-cli register-actor

Prompts:

1. Enter your actor username:
   (e.g., "@[email protected]")

2. Enter your actor URL:
   (e.g., "https://yourdomain.com/actor")

3. Enter your public key ID:
   (e.g., "https://yourdomain.com/actor#main-key")

send-post

Send an activity post to your followers and publish it on the DP site:

dp-cli send-post --path ./path_to_activity.json

Output:

Sending a post to followers...
Post sent successfully!
Response: { ... }

License

This project is licensed under the MIT License.

Resources

• Distributed Press Documentation:
  https://docs.distributed.press/

• Social Inbox Documentation:
  https://github.com/hyphacoop/social.distributed.press

• RC Module Documentation:
  https://www.npmjs.com/package/rc

• HTTP Signed Fetch:
  https://www.npmjs.com/package/http-signed-fetch

• Setting Up Node.js:
  https://nodejs.org/en/download/

Notes

• Security: Ensure that your .dprc file and any keys or tokens are stored securely and are not exposed publicly.
• Dependencies: Make sure you have the necessary dependencies installed as per the package.json file.