CLI

Installation

The CLI lives in the cli/ directory of the Blurt repository:

git clone https://github.com/fberrez/blurt.sh.git
cd blurt.sh/cli
bundle install

Configuration

The CLI reads credentials in priority order: flags > environment variables > config file.

Environment variables

export BLURT_API_URL=http://localhost:3000   # default
export BLURT_API_KEY=your-secret-key

Config file

Credentials can also be stored in ~/.config/blurt/config.yml. Use the built-in config command to manage it:

# Set your server URL and API key
blurt config set api_url https://your-vps.com
blurt config set api_key your-secret-key

# View current configuration (API key is masked)
blurt config show

Or edit the file directly at ~/.config/blurt/config.yml:

api_url: https://your-vps.com
api_key: your-secret-key

The config file is created with 0600 permissions (owner-only) to protect your API key.

Per-command flags

Override the URL or key for a single command:

blurt status --api-url https://your-vps.com --api-key your-key

Commands

blurt status

Check server health and queue overview. Does not require authentication (uses the /api/health endpoint).

$ blurt status

Blurt Status

  Server:     http://localhost:3000 (ok)
  Queue:      3 pending
  Sent:       42 total
  Failed:     1 total
  Platforms:  bluesky, mastodon, linkedin (3/6 configured)
  Worker:     connected (polling every 60s)

blurt queue

List posts in the queue. Requires BLURT_API_KEY.

$ blurt queue

3 post(s):

  FILENAME            PLATFORMS           STATUS  SCHEDULED
  hello.md            bluesky, mastodon   queue   —
  big-announce.md     bluesky, linkedin   queue   2026-04-01T09:00:00Z
  devto-article.md    devto               queue   —

Filter by status or platform:

# Show sent posts only
blurt queue --status sent

# Show failed posts for bluesky
blurt queue --status failed --platform bluesky

# Show everything
blurt queue --status all

blurt post

Create a new post. Pass content inline or read from a markdown file. Requires BLURT_API_KEY.

# Inline content
$ blurt post "Hello world!" --platforms bluesky,mastodon

Post created: 20260401-hello-world.md
  Platforms: bluesky, mastodon
  Status:    queue

# From a markdown file (reads frontmatter for platforms, title, scheduled_at)
$ blurt post --file ./my-post.md

Frontmatter example:

---
platforms:
  - bluesky
  - mastodon
title: My Article
scheduled_at: '2026-04-01T09:00:00Z'
---
Your post content here.

CLI flags override frontmatter values:

# File has platforms: [bluesky], but flag wins
blurt post --file ./my-post.md --platforms mastodon,linkedin

# All options
blurt post "Content" -p bluesky,mastodon -t "Title" --scheduled-at 2026-04-01T09:00:00Z

blurt publish

Force-publish a queued post immediately. Requires BLURT_API_KEY.

$ blurt publish my-post.md

Published: my-post.md
  Status: sent
  bluesky: https://bsky.app/profile/did:plc:xxx/post/abc123
  mastodon: https://mastodon.social/@user/123456789

If a platform fails, you’ll see the error inline:

$ blurt publish my-post.md

Published: my-post.md
  Status: sent
  bluesky: https://bsky.app/profile/did:plc:xxx/post/abc123
  linkedin: FAILED — Token expired

blurt delete

Remove a queued post. Requires BLURT_API_KEY.

$ blurt delete my-post.md

✔ Deleted: my-post.md

blurt config

Manage local configuration. Does not require authentication.

# Show current config (API key is masked)
$ blurt config show

Blurt Configuration

  api_url:  https://your-vps.com
  api_key:  sk-a********

  Config file: ~/.config/blurt/config.yml

# Set a config value
$ blurt config set api_url https://your-vps.com
✔ api_url = https://your-vps.com
  Saved to ~/.config/blurt/config.yml

$ blurt config set api_key sk-abcdef123456
✔ api_key = sk-a********
  Saved to ~/.config/blurt/config.yml

Valid keys: api_url, api_key. Running blurt config with no subcommand defaults to show.

blurt history

List published posts (the system of record). Requires BLURT_API_KEY.

$ blurt history

3 published post(s):

  FILENAME            PLATFORMS           PUBLISHED             URLS
  hello.md            bluesky, mastodon   2026-04-01T10:00:00Z  https://bsky.app/... (+1 more)
  big-announce.md     bluesky, linkedin   2026-03-31T14:30:00Z  https://bsky.app/... (+1 more)
  devto-article.md    devto               2026-03-30T09:00:00Z  https://dev.to/...

  Page 1 of 1 (3 total)

Filter by platform or page:

# Only bluesky posts
blurt history --platform bluesky

# Page 2
blurt history --page 2

How it works

The CLI is a thin client that talks to the Blurt HTTP API. It does not import Rails models or access the filesystem directly. This means it works against any Blurt server — your local dev server, a remote VPS, or a Docker container.

blurt CLI  ---->  HTTP API (localhost:3000 or remote)  ---->  Blurt engine

Built with Thor and Faraday.