nevo-david_postiz/HOW_TO_RUN.md

How to Run the Postiz CLI

There are several ways to run the CLI, depending on your needs.

Option 1: Direct Execution (Quick Test) ⚡

The built file at apps/cli/dist/index.js is already executable!

# From the monorepo root
node apps/cli/dist/index.js --help

# Or run it directly (it has a shebang)
./apps/cli/dist/index.js --help

# Example command
export POSTIZ_API_KEY=your_key
node apps/cli/dist/index.js posts:list

Option 2: Link Globally (Recommended for Development) 🔗

This creates a global postiz command you can use anywhere:

# From the monorepo root
cd apps/cli
pnpm link --global

# Now you can use it anywhere!
postiz --help
postiz posts:list
postiz posts:create -c "Hello!" -i "twitter-123"

# To unlink later
pnpm unlink --global

After linking, you can use postiz from any directory!

Option 3: Use pnpm Filter (From Root) 📦

# From the monorepo root
pnpm --filter postiz start -- --help
pnpm --filter postiz start -- posts:list
pnpm --filter postiz start -- posts:create -c "Hello" -i "twitter-123"

Option 4: Use npm/npx (After Publishing) 🌐

Once published to npm:

# Install globally
npm install -g postiz

# Or use with npx (no install)
npx postiz --help
npx postiz posts:list

Quick Setup Guide

Step 1: Build the CLI

# From monorepo root
pnpm run build:cli

Step 2: Set Your API Key

export POSTIZ_API_KEY=your_api_key_here

# To make it permanent, add to your shell profile:
echo 'export POSTIZ_API_KEY=your_api_key' >> ~/.bashrc
# or ~/.zshrc if you use zsh

Step 3: Choose Your Method

For quick testing:

node apps/cli/dist/index.js --help

For regular use (recommended):

cd apps/cli
pnpm link --global
postiz --help

Troubleshooting

"Command not found: postiz"

If you linked globally but still get this error:

# Check if it's linked
which postiz

# If not found, try linking again
cd apps/cli
pnpm link --global

# Or check your PATH
echo $PATH

"POSTIZ_API_KEY is not set"

export POSTIZ_API_KEY=your_key

# Verify it's set
echo $POSTIZ_API_KEY

Permission Denied

If you get permission errors:

# Make the file executable
chmod +x apps/cli/dist/index.js

# Then try again
./apps/cli/dist/index.js --help

Rebuild After Changes

After making code changes, rebuild:

pnpm run build:cli

If you linked globally, the changes will be reflected immediately (no need to re-link).

Testing the CLI

Test Help Command

postiz --help
postiz posts:create --help

Test with Sample Command (requires API key)

export POSTIZ_API_KEY=your_key

# List integrations
postiz integrations:list

# Create a test post
postiz posts:create \
  -c "Test post from CLI" \
  -i "your-integration-id"

Development Workflow

1. Make Changes

Edit files in apps/cli/src/

2. Rebuild

pnpm run build:cli

3. Test

# If linked globally
postiz --help

# Or direct execution
node apps/cli/dist/index.js --help

4. Watch Mode (Auto-rebuild)

# From apps/cli directory
pnpm run dev

# In another terminal, test your changes
postiz --help

Environment Variables

Required

• POSTIZ_API_KEY - Your Postiz API key (required for all operations)

Optional

• POSTIZ_API_URL - Custom API endpoint (default: https://api.postiz.com)

Setting Environment Variables

Temporary (current session):

export POSTIZ_API_KEY=your_key
export POSTIZ_API_URL=https://custom-api.com

Permanent (add to shell profile):

# For bash
echo 'export POSTIZ_API_KEY=your_key' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export POSTIZ_API_KEY=your_key' >> ~/.zshrc
source ~/.zshrc

Using Aliases

Create a convenient alias:

# Add to ~/.bashrc or ~/.zshrc
alias pz='postiz'

# Now you can use
pz posts:list
pz posts:create -c "Quick post" -i "twitter-123"

Production Deployment

Publish to npm

# From monorepo root
pnpm run publish-cli

# Or from apps/cli
cd apps/cli
pnpm run publish

Install from npm

# Global install
npm install -g postiz

# Project-specific
npm install postiz
npx postiz --help

Summary of Methods

Method	Command	Use Case
Direct Node	node apps/cli/dist/index.js	Quick testing, no installation
Direct Execution	./apps/cli/dist/index.js	Same as above, slightly shorter
Global Link	postiz (after pnpm link --global)	Recommended for development
pnpm Filter	pnpm --filter postiz start --	From monorepo root
npm Global	postiz (after npm i -g postiz)	After publishing to npm
npx	npx postiz	One-off usage without installing

Recommended Setup

For the best development experience:

# 1. Build
pnpm run build:cli

# 2. Link globally
cd apps/cli
pnpm link --global

# 3. Set API key
export POSTIZ_API_KEY=your_key

# 4. Test
postiz --help
postiz integrations:list

# 5. Start using!
postiz posts:create -c "My first post" -i "twitter-123"

Now you can use postiz from anywhere! 🚀