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.
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.
You can use dp-cli
without installation by running:
npx dp-cli <command>
To install dp-cli
globally, use:
npm install -g dp-cli
Once installed, you can use dp-cli
from anywhere in your terminal.
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.
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.
Once registered, create a new site by specifying the domain name and whether it should be public:
dp-cli create-site
To upload and publish static content to the DP site from a specified directory:
dp-cli publish ./folder_here
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.
- 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.
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 inapi.distributed.press.
as required.
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.
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
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 a website by creating a static copy from its HTTP URL:
dp-cli clone <site-id>
-
Fork the Repository: Visit the staticpub.distributed.press repository on GitHub and click the "Fork" button to create your own copy.
-
Clone Your Fork:
git clone https://github.com/hyphacoop/staticpub.distributed.press.git
cd staticpub.distributed.press
- Replace Domain, Username, and Name:
find . -type f -exec sed -i 's/staticpub\.distributed\.press/yourdomain\.com/g; s/dp/username/g; s/"Distributed Press"/"Your Name"/g' {} +
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
- Open your
.dprc
file (generated during setup). - Copy the value of
"publicKeyPem"
(including theBEGIN
andEND
lines). - Paste it into the
publicKeyPem
field in the JSON files mentioned above.
"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.
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.
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:
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 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.
Published the template? Now, let's send a post to your followers:
dp-cli send-post ./path_to_activity.json
dp-cli send-post ./posts/helloworld.jsonld
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
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.
Description:
Register a trial publisher account with Distributed Press:
Usage:
dp-cli register
Description:
Set your authentication token for API access.
Usage:
dp-cli set-auth-token
Prompt:
- Enter your authentication token.
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)
Description:
Upload and publish static content to the DP site from a specified directory:
Usage:
dp-cli publish ./folder_here
Description:
Clone a website by creating a static copy from its HTTP URL:
Usage:
dp-cli clone <site-id>
Description:
Generate a new RSA keypair and save it to your configuration.
Usage:
dp-cli generate-keypair
Description:
Register your ActivityPub actor with the Social Inbox.
Usage:
dp-cli register-actor
Prompts:
-
Enter your actor username:
(e.g., "@[email protected]") -
Enter your actor URL:
(e.g., "https://yourdomain.com/actor") -
Enter your public key ID:
(e.g., "https://yourdomain.com/actor#main-key")
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: { ... }
This project is licensed under the MIT License.
-
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/
- 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.