Skip to Content
CLI

CLI

Post to social media directly from your terminal. The @voxburst/cli package provides a full-featured command-line interface for VoxBurst.

Quick Start

Check prerequisites

You need Node.js 18 or later installed. Check your version:

node --version
# Should print v18.0.0 or higher

If you don’t have Node.js installed, download it from nodejs.org .

Get your API key

Sign in to your VoxBurst dashboard  and create an API key. Copy it — you’ll use it in the next step.

Keep your API key secret. Anyone with it can post to your connected accounts.

Install the CLI

npm install -g @voxburst/cli

The package name is @voxburst/cli but the command is voxburst. Do not run @voxburst/cli --help.

If voxburst command is not found after installing, your npm global bin directory may not be in your PATH. Fix it:

# For zsh (macOS default)
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc
source ~/.zshrc
 
# For bash
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

Then run voxburst --help to confirm it works.

Set your API key

voxburst config set api-key sk_your_api_key_here

Verify it’s working by checking your account:

voxburst whoami

You should see your account name and email. If you get an UNAUTHORIZED error, double-check that you pasted the key correctly.

Connect a social account

voxburst accounts connect twitter

This opens a browser window for OAuth authorization. Log in to the social account you want to connect and approve access. When you return to the terminal, the account will be confirmed as connected.

Run voxburst accounts list to see all connected accounts and their IDs.

Post something

voxburst post "Hello from VoxBurst! 🚀"

By default this posts to all of your connected accounts. You should see output like:

  Post published

  ID:        post_abc123
  Status:    published
  Platforms: twitter
  Created:   Mar 26, 2026 10:30

Copy that post ID — you can use it later to check analytics or delete the post.

If you always post to the same platforms, save yourself from typing --platforms every time:

voxburst config set default-platforms twitter,linkedin

Commands

Configuration

Manage CLI settings stored in ~/.voxburst/config.json.

voxburst config set api-key sk_xxx        # Set a config value
voxburst config get api-key               # Get a config value
voxburst config list                      # Show all config
voxburst config delete api-key            # Remove a config value

Authentication

voxburst whoami     # Show current account info

Posting

Create and publish posts from the command line.

# Post to all connected accounts
voxburst post "Hello world!"
 
# Post to specific platforms
voxburst post "Hello!" --platforms twitter,linkedin
 
# Schedule a post
voxburst post "Future post" --schedule "2026-03-01 14:00"
 
# Post with media
voxburst post "Check this out!" --media ./image.png,./photo.jpg
 
# Post from a JSON file
voxburst post --file ./post.json

post.json format:

{
  "content": "Post content here",
  "platforms": ["twitter", "linkedin"],
  "scheduledFor": "2026-03-01T14:00:00Z",
  "overrides": {
    "twitter": {
      "content": "Short tweet version"
    }
  }
}

Posts Management

voxburst posts list                        # List all posts
voxburst posts list --status scheduled    # Filter by status
voxburst posts get post_123               # Get a specific post
voxburst posts delete post_123            # Delete a post

Accounts

voxburst accounts list                    # List connected accounts
voxburst accounts connect twitter         # Connect a new account
voxburst accounts get acc_123             # Get account details
voxburst accounts disconnect acc_123      # Disconnect an account

Analytics

voxburst analytics post_123               # Analytics for a post
voxburst analytics account acc_123        # Account analytics
voxburst analytics account acc_123 --since 30d  # Last 30 days

Validation

Test whether content is valid for specific platforms before posting.

voxburst validate "Check this content"
voxburst validate "Check this" --platforms twitter,instagram

Debugging

voxburst debug request GET /v1/posts      # Make a raw API request
voxburst debug config                     # Show resolved configuration

Output Formats

FlagDescription
(default)Human-readable formatted output
--jsonMachine-readable JSON output
--quiet / -qMinimal output (e.g., just the post ID)

The --quiet flag is useful for scripts:

# Store the post ID in a variable
POST_ID=$(voxburst post "Hello!" --quiet)
echo "Created post: $POST_ID"

Configuration

Config file location: ~/.voxburst/config.json

Environment variables take precedence over the config file:

VariableDescription
VOXBURST_API_KEYYour API key
VOXBURST_API_URLAPI base URL (default: production)

CI/CD Integration

GitHub Actions

- name: Post release announcement
  env:
    VOXBURST_API_KEY: ${{ secrets.VOXBURST_API_KEY }}
  run: |
    voxburst post "🚀 Version ${{ github.ref_name }} released!" \
      --platforms twitter,linkedin

Batch posting from a script

for file in posts/*.json; do
  id=$(voxburst post --file "$file" --quiet)
  echo "Created: $id"
done

Cross-post to multiple platforms

voxburst post "Exciting news! 🎉" --platforms twitter,linkedin,facebook

Supported Platforms

twitter, linkedin, facebook, instagram, threads, bluesky, mastodon

Platform names in the CLI are lowercase (twitter, linkedin). The API uses uppercase constants (TWITTER, LINKEDIN).

Next Steps

  • Getting Started — Using the REST API directly instead of the CLI
  • Authentication — API key scopes and security best practices
  • SDKs — Integrate VoxBurst into your app with TypeScript, Go, or Python
  • API Reference — Full endpoint documentation
Last updated on
ChangelogGetting Started