socialbuffer

Minimal CLI for turning markdown files into queued Buffer posts for X and LinkedIn.

socialbuffer is the public name and primary command. tweetx remains available as a backward-compatible alias for now.

Run from source

Clone the repo, create a local .env, and run the CLI directly from source:

nvm use
cp .env.example .env
node ./bin/socialbuffer.js --help
node ./bin/socialbuffer.js post --file ./example-post.md --dry-run

The root .env is loaded automatically, so source usage works without a global install.

Node 20 is the supported runtime for development and CI.

Global install

Install the CLI globally so socialbuffer is available from any directory:

npm install -g .

When run outside this repo, socialbuffer looks for config in this order:

$SOCIALBUFFER_ENV_FILE
$TWEETX_ENV_FILE
$XDG_CONFIG_HOME/socialbuffer/.env
~/.config/socialbuffer/.env
~/.socialbuffer/.env
~/.config/tweetx/.env
~/.tweetx/.env
./.env

Use ~/.config/socialbuffer/.env for the public config path. The older tweetx config paths still work as legacy fallbacks.

Discover your channel

List Buffer channels:

node ./bin/socialbuffer.js channels

List only X/Twitter channels:

node ./bin/socialbuffer.js channels --service twitter

List only LinkedIn channels:

node ./bin/socialbuffer.js channels --service linkedin

With a global install, the same commands become:

socialbuffer channels --service twitter
socialbuffer channels --service linkedin

First command

node ./bin/socialbuffer.js post --file ./post.md --dry-run

Setup

Set these environment variables in one of the supported env files:

BUFFER_API_KEY=your_buffer_api_key
BUFFER_X_CHANNEL_ID=your_buffer_x_channel_id
BUFFER_LINKEDIN_CHANNEL_ID=your_buffer_linkedin_channel_id
X_BEARER_TOKEN=your_x_bearer_token

X_BEARER_TOKEN is only needed for the read-only analytics command.

Usage

Queue an X post in Buffer:

socialbuffer post --file ./post.md

Queue a LinkedIn post in Buffer:

socialbuffer post --platform linkedin --file ./post.md

Queue a post with one image:

socialbuffer post --file ./post.md --image ./shot.png

Queue a post with one remote image URL:

socialbuffer post --file ./post.md --image-url https://example.com/shot.png

Share immediately:

socialbuffer post --file ./post.md --mode shareNow

Preview the payload without sending anything:

socialbuffer post --file ./post.md --dry-run

Read X analytics:

socialbuffer analytics --username xdevelopers

Notes

• The first version reads the markdown file as source text and flattens markdown formatting before publish.
• channels uses Buffer's GraphQL API so it works with the API key from Buffer's API settings page.
• The CLI auto-loads values from global config files and then lets the current directory's .env override them.
• post defaults to platform x. Use --platform linkedin to target the configured LinkedIn channel.
• analytics uses the X API directly and expects X_BEARER_TOKEN in .env or a supported global env file.
• BUFFER_CHANNEL_ID remains supported as a legacy fallback for X only.
• YAML frontmatter is stripped if present at the top of the file.
• The current image path supports one local image or one remote image URL.

Built alongside DocsALot: convert your commits into documentation, social media posts on autopilot.