postiz - npm Package Compare versions

Comparing version 2.0.4 to 2.0.5

package.json

 {
   "name": "postiz",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Postiz CLI - Command line interface for the Postiz social media scheduling API",
@@ -5,0 +5,0 @@ "main": "dist/index.js",

README.md

 # Postiz CLI
 
-> Command-line interface for the Postiz social media scheduling platform
+**Social media automation CLI for AI agents** - Schedule posts across 28+ platforms programmatically.
 
-## Overview
+The Postiz CLI provides a command-line interface to the Postiz API, enabling developers and AI agents to automate social media posting, manage content, and handle media uploads across platforms like Twitter/X, LinkedIn, Reddit, YouTube, TikTok, Instagram, Facebook, and more.
 
-The Postiz CLI allows you to interact with the Postiz API from the command line, making it easy for developers and AI agents to automate social media scheduling, manage posts, and upload media.
+---
 
-## Quick Start
+## Installation
 
-### Installation
+### From npm (Recommended)
 
 ```bash
-# Install dependencies
+npm install -g postiz
+# or
+pnpm install -g postiz
+```
+
+### From Source
+
+```bash
+git clone https://github.com/gitroomhq/postiz-app.git
+cd postiz-app/apps/cli
 pnpm install
-
-# Build the CLI
 pnpm run build
+pnpm link --global
+```
 
-# Run locally (development)
-pnpm run start -- [command]
+### For Development
 
-# Or link globally
+```bash
+cd apps/cli
+pnpm install
+pnpm run build
 pnpm link --global
+
+# Or run directly without linking
+pnpm run start -- posts:list
 ```
 
-### Setup
+---
 
-Before using the CLI, you need to set your Postiz API key:
+## Setup
 
+**Required:** Set your Postiz API key
+
 ```bash
@@ -35,3 +51,3 @@ export POSTIZ_API_KEY=your_api_key_here
 
-Optionally, you can set a custom API URL:
+**Optional:** Custom API endpoint
 
@@ -42,214 +58,405 @@ ```bash
 
-## Usage
+---
 
+## Commands
+
+### Discovery & Settings
+
+**List all connected integrations**
 ```bash
-postiz <command> [options]
+postiz integrations:list
 ```
 
-### Commands
+Returns integration IDs, provider names, and metadata.
 
-#### Create a Post
+**Get integration settings schema**
+```bash
+postiz integrations:settings <integration-id>
+```
 
+Returns character limits, required settings, and available tools for fetching dynamic data.
+
+**Trigger integration tools**
 ```bash
-postiz posts:create -c "Your content here" -i "integration-id-1,integration-id-2"
+postiz integrations:trigger <integration-id> <method-name>
+postiz integrations:trigger <integration-id> <method-name> -d '{"key":"value"}'
 ```
 
-**Options:**
-- `-c, --content <text>` - Post/comment content (can be used multiple times)
-- `-m, --media <urls>` - Comma-separated media URLs for the corresponding `-c` (can be used multiple times)
-- `-i, --integrations <ids>` - Comma-separated integration IDs (required)
-- `-s, --schedule <date>` - Schedule date (ISO 8601)
-- `-d, --delay <ms>` - Delay between comments in milliseconds (default: 5000)
-- `-p, --provider-type <type>` - Provider type for platform-specific settings (e.g., reddit, youtube, x, tiktok)
-- `--settings <json>` - Provider-specific settings as JSON string
+Fetch dynamic data like Reddit flairs, YouTube playlists, LinkedIn companies, etc.
 
 **Examples:**
+```bash
+# Get Reddit flairs
+postiz integrations:trigger reddit-123 getFlairs -d '{"subreddit":"programming"}'
 
+# Get YouTube playlists
+postiz integrations:trigger youtube-456 getPlaylists
+
+# Get LinkedIn companies
+postiz integrations:trigger linkedin-789 getCompanies
+```
+
+---
+
+### Creating Posts
+
+**Simple scheduled post**
 ```bash
-# Simple post
-postiz posts:create -c "Hello World!" -i "twitter-123"
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "integration-id"
+```
 
-# Post with multiple images
-postiz posts:create \
-  -c "Check these out!" \
-  -m "img1.jpg,img2.jpg,img3.jpg" \
-  -i "twitter-123"
+**Draft post**
+```bash
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -t draft -i "integration-id"
+```
 
-# Post with comments, each having their own media
-postiz posts:create \
-  -c "Main post 🚀" -m "main.jpg,main2.jpg" \
-  -c "First comment 📸" -m "comment1.jpg" \
-  -c "Second comment 🎨" -m "comment2.jpg" \
-  -i "twitter-123"
+**Post with media**
+```bash
+postiz posts:create -c "Content" -m "img1.jpg,img2.jpg" -s "2024-12-31T12:00:00Z" -i "integration-id"
+```
 
-# Comments can contain semicolons!
+**Post with comments** (each comment can have its own media)
+```bash
 postiz posts:create \
-  -c "Main post" \
-  -c "Comment with semicolon; see, it works!" \
-  -c "Another comment; multiple; semicolons!" \
-  -i "twitter-123"
+  -c "Main post" -m "main.jpg" \
+  -c "First comment" -m "comment1.jpg" \
+  -c "Second comment" -m "comment2.jpg,comment3.jpg" \
+  -s "2024-12-31T12:00:00Z" \
+  -i "integration-id"
+```
 
-# Twitter thread with custom delay
-postiz posts:create \
-  -c "Thread 1/3" \
-  -c "Thread 2/3" \
-  -c "Thread 3/3" \
-  -d 2000 \
-  -i "twitter-123"
+**Multi-platform post**
+```bash
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "twitter-id,linkedin-id,facebook-id"
+```
 
-# Scheduled post
+**Platform-specific settings**
+```bash
 postiz posts:create \
-  -c "Future post" \
+  -c "Content" \
   -s "2024-12-31T12:00:00Z" \
-  -i "twitter-123"
+  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"Post Title","type":"text"}}]}' \
+  -i "reddit-id"
+```
 
-# With provider-specific settings
-postiz posts:create \
-  -c "Video description" \
-  -p youtube \
-  --settings '{"title":"My Video","type":"public"}' \
-  -i "youtube-123"
+**Complex post from JSON file**
+```bash
+postiz posts:create --json post.json
 ```
 
-### Provider-Specific Settings
+**Options:**
+- `-c, --content` - Post/comment content (use multiple times for posts with comments)
+- `-s, --date` - Schedule date in ISO 8601 format (REQUIRED)
+- `-t, --type` - Post type: "schedule" or "draft" (default: "schedule")
+- `-m, --media` - Comma-separated media URLs for corresponding `-c`
+- `-i, --integrations` - Comma-separated integration IDs (required)
+- `-d, --delay` - Delay between comments in milliseconds (default: 5000)
+- `--settings` - Platform-specific settings as JSON string
+- `-j, --json` - Path to JSON file with full post structure
+- `--shortLink` - Use short links (default: true)
 
-Many platforms support specific settings (Reddit subreddits, YouTube visibility, TikTok privacy, etc.):
+---
 
+### Managing Posts
+
+**List posts**
 ```bash
-# Reddit with subreddit settings
-postiz posts:create \
-  -c "Post content" \
-  -p reddit \
-  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Title","type":"text","url":"","is_flair_required":false}}]}' \
-  -i "reddit-123"
+postiz posts:list
+postiz posts:list --startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"
+postiz posts:list --customer "customer-id"
+```
 
-# YouTube with title and visibility
-postiz posts:create \
-  -c "Video description" \
-  -p youtube \
-  --settings '{"title":"My Video","type":"public","tags":[{"value":"tech","label":"Tech"}]}' \
-  -i "youtube-123"
+Defaults to last 30 days to next 30 days if dates not specified.
 
-# X (Twitter) with reply settings
-postiz posts:create \
-  -c "Tweet" \
-  -p x \
-  --settings '{"who_can_reply_post":"everyone"}' \
-  -i "twitter-123"
+**Delete post**
+```bash
+postiz posts:delete <post-id>
 ```
 
-See **[PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md)** for complete documentation on all platform-specific settings.
+---
+
+### Media Upload
+
+**Upload file and get URL**
+```bash
+postiz upload <file-path>
 ```
 
-#### List Posts
+**Supported formats:**
+- **Images:** PNG, JPG, JPEG, GIF, WEBP, SVG, BMP, ICO
+- **Videos:** MP4, MOV, AVI, MKV, WEBM, FLV, WMV, M4V, MPEG, MPG, 3GP
+- **Audio:** MP3, WAV, OGG, AAC, FLAC, M4A
+- **Documents:** PDF, DOC, DOCX
 
+**Example:**
 ```bash
-postiz posts:list [options]
+RESULT=$(postiz upload video.mp4)
+PATH=$(echo "$RESULT" | jq -r '.path')
+postiz posts:create -c "Check out my video!" -m "$PATH" -i "tiktok-id"
 ```
 
-**Options:**
-- `-p, --page <number>` - Page number (default: 1)
-- `-l, --limit <number>` - Posts per page (default: 10)
-- `-s, --search <query>` - Search query
+---
 
-**Examples:**
+## Platform-Specific Features
 
+### Reddit
 ```bash
-# List all posts
-postiz posts:list
+# Get available flairs
+postiz integrations:trigger reddit-id getFlairs -d '{"subreddit":"programming"}'
 
-# With pagination
-postiz posts:list -p 2 -l 20
+# Post with subreddit and flair
+postiz posts:create \
+  -c "Content" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Post","type":"text","is_flair_required":true,"flair":{"id":"flair-123","name":"Discussion"}}}]}' \
+  -i "reddit-id"
+```
 
-# Search posts
-postiz posts:list -s "keyword"
+### YouTube
+```bash
+# Get playlists
+postiz integrations:trigger youtube-id getPlaylists
+
+# Upload video with metadata
+postiz posts:create \
+  -c "Video description" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"title":"Video Title","type":"public","tags":[{"value":"tech","label":"Tech"}],"playlistId":"playlist-id"}' \
+  -m "video.mp4" \
+  -i "youtube-id"
 ```
 
-#### Delete a Post
+### TikTok
+```bash
+postiz posts:create \
+  -c "Video caption #fyp" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"privacy":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true}' \
+  -m "video.mp4" \
+  -i "tiktok-id"
+```
 
+### LinkedIn
 ```bash
-postiz posts:delete <post-id>
+# Get companies you can post to
+postiz integrations:trigger linkedin-id getCompanies
+
+# Post as company
+postiz posts:create \
+  -c "Company announcement" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"companyId":"company-123"}' \
+  -i "linkedin-id"
 ```
 
-**Example:**
+### X (Twitter)
+```bash
+# Create thread
+postiz posts:create \
+  -c "Thread 1/3 🧵" \
+  -c "Thread 2/3" \
+  -c "Thread 3/3" \
+  -s "2024-12-31T12:00:00Z" \
+  -d 2000 \
+  -i "twitter-id"
 
+# With reply settings
+postiz posts:create \
+  -c "Tweet content" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"who_can_reply_post":"everyone"}' \
+  -i "twitter-id"
+```
+
+### Instagram
 ```bash
-postiz posts:delete abc123xyz
+# Regular post
+postiz posts:create \
+  -c "Caption #hashtag" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"post_type":"post"}' \
+  -m "image.jpg" \
+  -i "instagram-id"
+
+# Story
+postiz posts:create \
+  -c "" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"post_type":"story"}' \
+  -m "story.jpg" \
+  -i "instagram-id"
 ```
 
-#### List Integrations
+**See [PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md) for all 28+ platforms.**
 
+---
+
+## Features for AI Agents
+
+### Discovery Workflow
+The CLI enables dynamic discovery of integration capabilities:
+
+1. **List integrations** - Get available social media accounts
+2. **Get settings** - Retrieve character limits, required fields, and available tools
+3. **Trigger tools** - Fetch dynamic data (flairs, playlists, boards, etc.)
+4. **Create posts** - Use discovered data in posts
+
+This allows AI agents to adapt to different platforms without hardcoded knowledge.
+
+### JSON Mode
+For complex posts with multiple platforms and settings:
+
 ```bash
-postiz integrations:list
+postiz posts:create --json complex-post.json
 ```
 
-Shows all connected social media accounts.
+JSON structure:
+```json
+{
+  "integrations": ["twitter-123", "linkedin-456"],
+  "posts": [
+    {
+      "provider": "twitter",
+      "post": [
+        {
+          "content": "Tweet version",
+          "image": ["twitter-image.jpg"]
+        }
+      ]
+    },
+    {
+      "provider": "linkedin",
+      "post": [
+        {
+          "content": "LinkedIn version with more context...",
+          "image": ["linkedin-image.jpg"]
+        }
+      ],
+      "settings": {
+        "__type": "linkedin",
+        "companyId": "company-123"
+      }
+    }
+  ]
+}
+```
 
-#### Upload a File
+### All Output is JSON
+Every command outputs JSON for easy parsing:
 
 ```bash
-postiz upload <file-path>
+INTEGRATIONS=$(postiz integrations:list | jq -r '.')
+REDDIT_ID=$(echo "$INTEGRATIONS" | jq -r '.[] | select(.identifier=="reddit") | .id')
 ```
 
-**Example:**
+### Threading Support
+Comments are automatically converted to threads/replies based on platform:
+- **Twitter/X**: Thread of tweets
+- **Reddit**: Comment replies
+- **LinkedIn**: Comment on post
+- **Instagram**: First comment
 
 ```bash
-postiz upload ./images/photo.png
+postiz posts:create \
+  -c "Main post" \
+  -c "Comment 1" \
+  -c "Comment 2" \
+  -i "integration-id"
 ```
 
-## Development
+---
 
-### Project Structure
+## Common Workflows
 
+### Reddit Post with Flair
+```bash
+#!/bin/bash
+REDDIT_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')
+FLAIRS=$(postiz integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
+FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')
+
+postiz posts:create \
+  -c "My post content" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings "{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"Post Title\",\"type\":\"text\",\"is_flair_required\":true,\"flair\":{\"id\":\"$FLAIR_ID\",\"name\":\"Discussion\"}}}]}" \
+  -i "$REDDIT_ID"
 ```
-apps/cli/
-├── src/
-│   ├── index.ts              # CLI entry point
-│   ├── api.ts                # API client
-│   ├── config.ts             # Configuration handler
-│   └── commands/
-│       ├── posts.ts          # Post commands
-│       ├── integrations.ts   # Integration commands
-│       └── upload.ts         # Upload commands
-├── package.json
-├── tsconfig.json
-├── tsup.config.ts
-├── README.md
-└── SKILL.md                  # AI agent usage guide
-```
 
-### Scripts
+### YouTube Video Upload
+```bash
+#!/bin/bash
+VIDEO=$(postiz upload video.mp4)
+VIDEO_PATH=$(echo "$VIDEO" | jq -r '.path')
 
-- `pnpm run dev` - Watch mode for development
-- `pnpm run build` - Build the CLI
-- `pnpm run start` - Run the built CLI
+postiz posts:create \
+  -c "Video description..." \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"title":"My Video","type":"public","tags":[{"value":"tech","label":"Tech"}]}' \
+  -m "$VIDEO_PATH" \
+  -i "youtube-id"
+```
 
-### Building
+### Multi-Platform Campaign
+```bash
+#!/bin/bash
+postiz posts:create \
+  -c "Same content everywhere" \
+  -s "2024-12-31T12:00:00Z" \
+  -m "image.jpg" \
+  -i "twitter-id,linkedin-id,facebook-id"
+```
 
-The CLI uses `tsup` for building:
+### Batch Scheduling
+```bash
+#!/bin/bash
+DATES=("2024-02-14T09:00:00Z" "2024-02-15T09:00:00Z" "2024-02-16T09:00:00Z")
+CONTENT=("Monday motivation 💪" "Tuesday tips 💡" "Wednesday wisdom 🧠")
 
-```bash
-pnpm run build
+for i in "${!DATES[@]}"; do
+  postiz posts:create \
+    -c "${CONTENT[$i]}" \
+    -s "${DATES[$i]}" \
+    -i "twitter-id"
+done
 ```
 
-This creates a `dist/` directory with:
-- Compiled JavaScript
-- Type declarations
-- Source maps
-- Executable shebang for Node.js
+---
 
-## For AI Agents
+## Documentation
 
-See [SKILL.md](./SKILL.md) for detailed usage patterns and examples for AI agents.
+**For AI Agents:**
+- **[SKILL.md](./SKILL.md)** - Complete skill reference with patterns and examples
 
-## API Reference
+**Deep-Dive Guides:**
+- **[HOW_TO_RUN.md](./HOW_TO_RUN.md)** - Installation and setup methods
+- **[COMMAND_LINE_GUIDE.md](./COMMAND_LINE_GUIDE.md)** - Complete command syntax reference
+- **[PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md)** - All platform settings schemas
+- **[INTEGRATION_TOOLS_WORKFLOW.md](./INTEGRATION_TOOLS_WORKFLOW.md)** - Tools workflow guide
+- **[INTEGRATION_SETTINGS_DISCOVERY.md](./INTEGRATION_SETTINGS_DISCOVERY.md)** - Settings discovery
+- **[SUPPORTED_FILE_TYPES.md](./SUPPORTED_FILE_TYPES.md)** - Media format reference
+- **[PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md)** - Code architecture
+- **[PUBLISHING.md](./PUBLISHING.md)** - npm publishing guide
 
+**Examples:**
+- **[examples/EXAMPLES.md](./examples/EXAMPLES.md)** - Comprehensive examples
+- **[examples/](./examples/)** - Ready-to-use scripts and JSON files
+
+---
+
+## API Endpoints
+
 The CLI interacts with these Postiz API endpoints:
 
-- `POST /public/v1/posts` - Create a post
-- `GET /public/v1/posts` - List posts
-- `DELETE /public/v1/posts/:id` - Delete a post
-- `GET /public/v1/integrations` - List integrations
-- `POST /public/v1/upload` - Upload media
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/public/v1/posts` | POST | Create a post |
+| `/public/v1/posts` | GET | List posts |
+| `/public/v1/posts/:id` | DELETE | Delete a post |
+| `/public/v1/integrations` | GET | List integrations |
+| `/public/v1/integration-settings/:id` | GET | Get integration settings |
+| `/public/v1/integration-trigger/:id` | POST | Trigger integration tool |
+| `/public/v1/upload` | POST | Upload media |
 
+---
+
 ## Environment Variables
@@ -262,51 +469,99 @@
 
+---
+
 ## Error Handling
 
-The CLI provides user-friendly error messages:
+The CLI provides clear error messages with exit codes:
 
-- ✅ Success messages with green checkmarks
-- ❌ Error messages with red X marks
-- 📋 Info messages with emojis
-- Exit code 0 for success, 1 for errors
+- **Exit code 0**: Success
+- **Exit code 1**: Error occurred
 
-## Examples
+**Common errors:**
 
-### Basic Workflow
+| Error | Solution |
+|-------|----------|
+| `POSTIZ_API_KEY is not set` | Set environment variable: `export POSTIZ_API_KEY=key` |
+| `Integration not found` | Run `integrations:list` to get valid IDs |
+| `startDate/endDate required` | Use ISO 8601 format: `"2024-12-31T12:00:00Z"` |
+| `Invalid settings` | Check `integrations:settings` for required fields |
+| `Tool not found` | Check available tools in `integrations:settings` output |
+| `Upload failed` | Verify file exists and format is supported |
 
-```bash
-# 1. Set API key
-export POSTIZ_API_KEY=your_key
+---
 
-# 2. Check connected integrations
-postiz integrations:list
+## Development
 
-# 3. Create a post
-postiz posts:create -c "Hello from CLI!" -i "twitter-123"
+### Project Structure
 
-# 4. List posts
-postiz posts:list
+```
+apps/cli/
+├── src/
+│   ├── index.ts              # CLI entry point with yargs
+│   ├── api.ts                # PostizAPI client class
+│   ├── config.ts             # Environment configuration
+│   └── commands/
+│       ├── posts.ts          # Post management commands
+│       ├── integrations.ts   # Integration commands
+│       └── upload.ts         # Media upload command
+├── examples/                 # Example scripts and JSON files
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts            # Build configuration
+├── README.md                 # This file
+└── SKILL.md                  # AI agent reference
+```
 
-# 5. Delete a post
-postiz posts:delete post-id-123
+### Scripts
+
+```bash
+pnpm run dev       # Watch mode for development
+pnpm run build     # Build the CLI
+pnpm run start     # Run the built CLI
 ```
 
-### Scheduled Posting
+### Building
 
+The CLI uses `tsup` for bundling:
+
 ```bash
-# Schedule posts for different times
-postiz posts:create -c "Morning post" -s "2024-01-15T09:00:00Z"
-postiz posts:create -c "Afternoon post" -s "2024-01-15T15:00:00Z"
-postiz posts:create -c "Evening post" -s "2024-01-15T20:00:00Z"
+pnpm run build
 ```
 
-### Media Upload Workflow
+Output in `dist/`:
+- `index.js` - Bundled executable with shebang
+- `index.js.map` - Source map
 
+---
+
+## Quick Reference
+
 ```bash
-# Upload an image
-postiz upload ./image.png
+# Environment setup
+export POSTIZ_API_KEY=your_key
 
-# The response includes the URL, use it in a post
-postiz posts:create -c "Check this out!" --image "url-from-upload"
+# Discovery
+postiz integrations:list                           # List integrations
+postiz integrations:settings <id>                  # Get settings
+postiz integrations:trigger <id> <method> -d '{}'  # Fetch data
+
+# Posting (date is required)
+postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" -i "id"                    # Simple
+postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" -t draft -i "id"          # Draft
+postiz posts:create -c "text" -m "img.jpg" -s "2024-12-31T12:00:00Z" -i "id"      # With media
+postiz posts:create -c "main" -c "comment" -s "2024-12-31T12:00:00Z" -i "id"      # With comment
+postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" --settings '{}' -i "id"   # Platform-specific
+postiz posts:create --json file.json                                               # Complex
+
+# Management
+postiz posts:list                                  # List posts
+postiz posts:delete <id>                          # Delete post
+postiz upload <file>                              # Upload media
+
+# Help
+postiz --help                                     # Show help
+postiz posts:create --help                        # Command help
 ```
 
+---
+
 ## Contributing
@@ -316,2 +571,11 @@
 
+To contribute:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes in `apps/cli/`
+4. Run tests: `pnpm run build`
+5. Submit a pull request
+
+---
+
 ## License
@@ -321,6 +585,31 @@
 
+---
+
 ## Links
 
-- [Postiz Website](https://postiz.com)
-- [API Documentation](https://postiz.com/api-docs)
-- [GitHub Repository](https://github.com/gitroomhq/postiz-app)
+- **Website:** [postiz.com](https://postiz.com)
+- **API Docs:** [postiz.com/api-docs](https://postiz.com/api-docs)
+- **GitHub:** [gitroomhq/postiz-app](https://github.com/gitroomhq/postiz-app)
+- **Issues:** [Report bugs](https://github.com/gitroomhq/postiz-app/issues)
+
+---
+
+## Supported Platforms
+
+28+ platforms including:
+
+| Platform | Integration Tools | Settings |
+|----------|------------------|----------|
+| Twitter/X | getLists, getCommunities | who_can_reply_post |
+| LinkedIn | getCompanies | companyId, carousel |
+| Reddit | getFlairs, searchSubreddits | subreddit, title, flair |
+| YouTube | getPlaylists, getCategories | title, type, tags, playlistId |
+| TikTok | - | privacy, duet, stitch |
+| Instagram | - | post_type (post/story) |
+| Facebook | getPages | - |
+| Pinterest | getBoards, getBoardSections | - |
+| Discord | getChannels | - |
+| Slack | getChannels | - |
+| And 18+ more... | | |
+
+**See [PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md) for complete documentation.**

SKILL.md

@@ -1,468 +0,585 @@
-# Postiz CLI Skill
+| Property | Value |
+|----------|-------|
+| **name** | postiz |
+| **description** | Social media automation CLI for scheduling posts across 28+ platforms |
+| **allowed-tools** | Bash(postiz:*) |
 
-## Description
+---
 
-The Postiz CLI is a command-line interface for interacting with the Postiz social media scheduling API. It allows AI agents and developers to programmatically manage posts, integrations, and media uploads.
+## Core Workflow
 
-## Prerequisites
+The fundamental pattern for using Postiz CLI:
 
-- API Key: You need a valid Postiz API key
-- Set the environment variable: `export POSTIZ_API_KEY=your_api_key`
-- Optional: Set custom API URL with `export POSTIZ_API_URL=https://your-api-url.com`
+1. **Discover** - List integrations and get their settings
+2. **Fetch** - Use integration tools to retrieve dynamic data (flairs, playlists, companies)
+3. **Prepare** - Upload media files if needed
+4. **Post** - Create posts with content, media, and platform-specific settings
 
-## Installation
-
 ```bash
-# From the monorepo root
-pnpm install
+# 1. Discover
+postiz integrations:list
+postiz integrations:settings <integration-id>
 
-# Build the CLI
-pnpm --filter postiz run build
+# 2. Fetch (if needed)
+postiz integrations:trigger <integration-id> <method> -d '{"key":"value"}'
 
-# Link globally (optional)
-cd apps/cli
-pnpm link --global
+# 3. Prepare
+postiz upload image.jpg
+
+# 4. Post
+postiz posts:create -c "Content" -m "image.jpg" -i "<integration-id>"
 ```
 
-## Available Commands
+---
 
-### Posts Management
+## Essential Commands
 
-#### Create a Post
+### Setup
 
-The CLI supports both **simple** and **complex** post creation:
+```bash
+# Required environment variable
+export POSTIZ_API_KEY=your_api_key_here
 
-##### Simple Post Creation (Command-line)
+# Optional custom API URL
+export POSTIZ_API_URL=https://custom-api-url.com
+```
 
+### Integration Discovery
+
 ```bash
-postiz posts:create -c "Your post content" -i "integration-id-1,integration-id-2"
+# List all connected integrations
+postiz integrations:list
+
+# Get settings schema for specific integration
+postiz integrations:settings <integration-id>
+
+# Trigger integration tool to fetch dynamic data
+postiz integrations:trigger <integration-id> <method-name>
+postiz integrations:trigger <integration-id> <method-name> -d '{"param":"value"}'
 ```
 
-Options:
-- `-c, --content <text>`: Post content/text
-- `-i, --integrations <ids>`: Comma-separated integration IDs (required)
-- `-s, --schedule <date>`: Schedule date in ISO 8601 format
-- `--image <urls>`: Comma-separated image URLs or paths (multiple images supported)
-- `--comments <text>`: Semicolon-separated comments
-- `--shortLink`: Use URL shortener (default: true)
+### Creating Posts
 
-Examples:
 ```bash
-# Create immediate post
-postiz posts:create -c "Hello World!" -i "twitter-123,linkedin-456"
+# Simple post (date is REQUIRED)
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "integration-id"
 
-# Create scheduled post
-postiz posts:create -c "Future post" -s "2024-12-31T12:00:00Z" -i "twitter-123"
+# Draft post
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -t draft -i "integration-id"
 
-# Create post with multiple images
-postiz posts:create -c "Check these out!" --image "url1.jpg,url2.jpg,url3.jpg" -i "twitter-123"
+# Post with media
+postiz posts:create -c "Content" -m "img1.jpg,img2.jpg" -s "2024-12-31T12:00:00Z" -i "integration-id"
 
-# Create post with comments (simple)
-postiz posts:create -c "Main post" --comments "First comment;Second comment" -i "twitter-123"
-```
+# Post with comments (each with own media)
+postiz posts:create \
+  -c "Main post" -m "main.jpg" \
+  -c "First comment" -m "comment1.jpg" \
+  -c "Second comment" -m "comment2.jpg,comment3.jpg" \
+  -s "2024-12-31T12:00:00Z" \
+  -i "integration-id"
 
-##### Complex Post Creation (JSON File)
+# Multi-platform post
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "twitter-id,linkedin-id,facebook-id"
 
-For posts with **comments that have their own media**, use JSON files:
+# Platform-specific settings
+postiz posts:create \
+  -c "Content" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Post","type":"text"}}]}' \
+  -i "reddit-id"
 
-```bash
-postiz posts:create --json ./my-post.json
+# Complex post from JSON file
+postiz posts:create --json post.json
 ```
 
-**JSON Structure:**
-```json
-{
-  "type": "now",
-  "date": "2024-01-15T12:00:00Z",
-  "shortLink": true,
-  "tags": [],
-  "posts": [
-    {
-      "integration": { "id": "twitter-123" },
-      "value": [
-        {
-          "content": "Main post with media 🚀",
-          "image": [
-            { "id": "img1", "path": "https://example.com/main1.jpg" },
-            { "id": "img2", "path": "https://example.com/main2.jpg" }
-          ]
-        },
-        {
-          "content": "First comment with its own media 📸",
-          "image": [
-            { "id": "img3", "path": "https://example.com/comment1.jpg" }
-          ],
-          "delay": 5000
-        },
-        {
-          "content": "Second comment with different media 🎨",
-          "image": [
-            { "id": "img4", "path": "https://example.com/comment2.jpg" }
-          ],
-          "delay": 10000
-        }
-      ],
-      "settings": { "__type": "EmptySettings" }
-    }
-  ]
-}
+### Managing Posts
+
+```bash
+# List posts (defaults to last 30 days to next 30 days)
+postiz posts:list
+
+# List posts in date range
+postiz posts:list --startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"
+
+# Delete post
+postiz posts:delete <post-id>
 ```
 
-**Key Features:**
-- ✅ **Multiple posts** to different platforms in one request
-- ✅ **Each post can have multiple values** (main post + comments/thread)
-- ✅ **Each value can have multiple images** (array of MediaDto)
-- ✅ **Delays between comments** (in milliseconds)
-- ✅ **Platform-specific content** (different content per integration)
+### Media Upload
 
-See `examples/` directory for:
-- `post-with-comments.json` - Post with comments, each having their own media
-- `multi-platform-post.json` - Post to multiple platforms with different content
-- `thread-post.json` - Create a Twitter thread with 5 tweets
-- `EXAMPLES.md` - Comprehensive guide with all use cases
+```bash
+# Upload file and get URL
+postiz upload image.jpg
 
-#### List Posts
-```bash
-postiz posts:list
+# Supports: images (PNG, JPG, GIF, WEBP, SVG), videos (MP4, MOV, AVI, MKV, WEBM),
+# audio (MP3, WAV, OGG, AAC), documents (PDF, DOC, DOCX)
 ```
 
-Options:
-- `-p, --page <number>`: Page number (default: 1)
-- `-l, --limit <number>`: Posts per page (default: 10)
-- `-s, --search <query>`: Search query
+---
 
-Examples:
+## Common Patterns
+
+### Pattern 1: Discover & Use Integration Tools
+
+**Reddit - Get flairs for a subreddit:**
 ```bash
-# List all posts
-postiz posts:list
+# Get Reddit integration ID
+REDDIT_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')
 
-# List with pagination
-postiz posts:list -p 2 -l 20
+# Fetch available flairs
+FLAIRS=$(postiz integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
+FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')
 
-# Search posts
-postiz posts:list -s "hello"
+# Use in post
+postiz posts:create \
+  -c "My post content" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings "{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"Post Title\",\"type\":\"text\",\"is_flair_required\":true,\"flair\":{\"id\":\"$FLAIR_ID\",\"name\":\"Discussion\"}}}]}" \
+  -i "$REDDIT_ID"
 ```
 
-#### Delete a Post
+**YouTube - Get playlists:**
 ```bash
-postiz posts:delete <post-id>
+YOUTUBE_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="youtube") | .id')
+PLAYLISTS=$(postiz integrations:trigger "$YOUTUBE_ID" getPlaylists)
+PLAYLIST_ID=$(echo "$PLAYLISTS" | jq -r '.output[0].id')
+
+postiz posts:create \
+  -c "Video description" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings "{\"title\":\"My Video\",\"type\":\"public\",\"playlistId\":\"$PLAYLIST_ID\"}" \
+  -m "video.mp4" \
+  -i "$YOUTUBE_ID"
 ```
 
-Example:
+**LinkedIn - Post as company:**
 ```bash
-postiz posts:delete abc123xyz
+LINKEDIN_ID=$(postiz integrations:list | jq -r '.[] | select(.identifier=="linkedin") | .id')
+COMPANIES=$(postiz integrations:trigger "$LINKEDIN_ID" getCompanies)
+COMPANY_ID=$(echo "$COMPANIES" | jq -r '.output[0].id')
+
+postiz posts:create \
+  -c "Company announcement" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings "{\"companyId\":\"$COMPANY_ID\"}" \
+  -i "$LINKEDIN_ID"
 ```
 
-### Integrations
+### Pattern 2: Upload Media Before Posting
 
-#### List Connected Integrations
 ```bash
-postiz integrations:list
-```
+# Upload multiple files
+VIDEO_RESULT=$(postiz upload video.mp4)
+VIDEO_PATH=$(echo "$VIDEO_RESULT" | jq -r '.path')
 
-This command shows all connected social media accounts and their IDs, which can be used when creating posts.
+THUMB_RESULT=$(postiz upload thumbnail.jpg)
+THUMB_PATH=$(echo "$THUMB_RESULT" | jq -r '.path')
 
-### Media Upload
-
-#### Upload a File
-```bash
-postiz upload <file-path>
+# Use in post
+postiz posts:create \
+  -c "Check out my video!" \
+  -s "2024-12-31T12:00:00Z" \
+  -m "$VIDEO_PATH" \
+  -i "tiktok-id"
 ```
 
-Example:
+### Pattern 3: Twitter Thread
+
 ```bash
-postiz upload ./images/photo.png
+postiz posts:create \
+  -c "🧵 Thread starter (1/4)" -m "intro.jpg" \
+  -c "Point one (2/4)" -m "point1.jpg" \
+  -c "Point two (3/4)" -m "point2.jpg" \
+  -c "Conclusion (4/4)" -m "outro.jpg" \
+  -s "2024-12-31T12:00:00Z" \
+  -d 2000 \
+  -i "twitter-id"
 ```
 
-Supported formats: PNG, JPG, JPEG, GIF
+### Pattern 4: Multi-Platform Campaign
 
-## Usage for AI Agents
-
-AI agents can use this CLI to automate social media scheduling. The CLI supports both simple and advanced post structures, including posts with comments where each has its own media.
-
-### Understanding the Post Structure
-
-```typescript
-CreatePostDto {
-  type: 'now' | 'schedule' | 'draft' | 'update',
-  date: string,              // ISO 8601 timestamp
-  shortLink: boolean,        // Enable URL shortening
-  tags: Tag[],              // Array of tags
-  posts: [                  // Can post to multiple platforms
+```bash
+# Create JSON file with platform-specific content
+cat > campaign.json << 'EOF'
+{
+  "integrations": ["twitter-123", "linkedin-456", "facebook-789"],
+  "posts": [
     {
-      integration: { id: string },    // Platform integration ID
-      value: [                        // Main post + comments/thread
+      "provider": "twitter",
+      "post": [
         {
-          content: string,            // Text content
-          image: MediaDto[],          // Array of media (multiple images)
-          delay?: number,             // Delay in ms (for comments)
-          id?: string                 // Optional ID
+          "content": "Short tweet version #tech",
+          "image": ["twitter-image.jpg"]
         }
-      ],
-      settings: { __type: 'EmptySettings' }
+      ]
+    },
+    {
+      "provider": "linkedin",
+      "post": [
+        {
+          "content": "Professional LinkedIn version with more context...",
+          "image": ["linkedin-image.jpg"]
+        }
+      ]
     }
   ]
 }
+EOF
+
+postiz posts:create --json campaign.json
 ```
 
-### Common Patterns
+### Pattern 5: Validate Settings Before Posting
 
-### Pattern 1: Create and Schedule Multiple Posts
-```bash
-# Set API key once
-export POSTIZ_API_KEY=your_key
+```javascript
+const { execSync } = require('child_process');
 
-# Create posts programmatically
-postiz posts:create -c "Morning update" -s "2024-01-15T09:00:00Z" -i "twitter-123"
-postiz posts:create -c "Afternoon update" -s "2024-01-15T15:00:00Z" -i "twitter-123"
-postiz posts:create -c "Evening update" -s "2024-01-15T20:00:00Z" -i "twitter-123"
-```
+function validateAndPost(content, integrationId, settings) {
+  // Get integration settings
+  const settingsResult = execSync(
+    `postiz integrations:settings ${integrationId}`,
+    { encoding: 'utf-8' }
+  );
+  const schema = JSON.parse(settingsResult);
 
-### Pattern 2: Upload Media and Create Post
-```bash
-# First, upload the media
-UPLOAD_RESULT=$(postiz upload ./image.png)
+  // Check character limit
+  if (content.length > schema.output.maxLength) {
+    console.warn(`Content exceeds ${schema.output.maxLength} chars, truncating...`);
+    content = content.substring(0, schema.output.maxLength - 3) + '...';
+  }
 
-# Extract the URL from the result (you'll need to parse the JSON)
-# Then create post with the media URL
-postiz posts:create -c "Check out this image!" --image "<url-from-upload>"
+  // Create post
+  const result = execSync(
+    `postiz posts:create -c "${content}" -s "2024-12-31T12:00:00Z" --settings '${JSON.stringify(settings)}' -i "${integrationId}"`,
+    { encoding: 'utf-8' }
+  );
+
+  return JSON.parse(result);
+}
 ```
 
-### Pattern 3: Check Integrations Before Posting
+### Pattern 6: Batch Scheduling
+
 ```bash
-# List available integrations
-postiz integrations:list
+#!/bin/bash
 
-# Use the integration IDs from the response to create posts
-postiz posts:create -c "Multi-platform post" -i "twitter-123,linkedin-456,facebook-789"
-```
+# Schedule posts for the week
+DATES=(
+  "2024-02-14T09:00:00Z"
+  "2024-02-15T09:00:00Z"
+  "2024-02-16T09:00:00Z"
+)
 
-### Pattern 4: Manage Existing Posts
-```bash
-# List all posts to get IDs
-postiz posts:list
+CONTENT=(
+  "Monday motivation 💪"
+  "Tuesday tips 💡"
+  "Wednesday wisdom 🧠"
+)
 
-# Delete a specific post
-postiz posts:delete <post-id-from-list>
+for i in "${!DATES[@]}"; do
+  postiz posts:create \
+    -c "${CONTENT[$i]}" \
+    -s "${DATES[$i]}" \
+    -i "twitter-id" \
+    -m "post-${i}.jpg"
+  echo "Scheduled: ${CONTENT[$i]} for ${DATES[$i]}"
+done
 ```
 
-### Pattern 5: Create Post with Comments and Media (Advanced)
+### Pattern 7: Error Handling & Retry
 
-```bash
-# Create a JSON file programmatically
-cat > post.json << 'EOF'
-{
-  "type": "now",
-  "date": "2024-01-15T12:00:00Z",
-  "shortLink": true,
-  "tags": [],
-  "posts": [{
-    "integration": { "id": "twitter-123" },
-    "value": [
-      {
-        "content": "Main post with 2 images 🚀",
-        "image": [
-          { "id": "1", "path": "https://example.com/img1.jpg" },
-          { "id": "2", "path": "https://example.com/img2.jpg" }
-        ]
-      },
-      {
-        "content": "First comment with its own image 📸",
-        "image": [
-          { "id": "3", "path": "https://example.com/comment-img.jpg" }
-        ],
-        "delay": 5000
+```javascript
+const { execSync } = require('child_process');
+
+async function postWithRetry(content, integrationId, date, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const result = execSync(
+        `postiz posts:create -c "${content}" -s "${date}" -i "${integrationId}"`,
+        { encoding: 'utf-8', stdio: 'pipe' }
+      );
+      console.log('✅ Post created successfully');
+      return JSON.parse(result);
+    } catch (error) {
+      console.error(`❌ Attempt ${attempt} failed: ${error.message}`);
+
+      if (attempt < maxRetries) {
+        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
+        console.log(`⏳ Retrying in ${delay}ms...`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      } else {
+        throw new Error(`Failed after ${maxRetries} attempts`);
       }
-    ],
-    "settings": { "__type": "EmptySettings" }
-  }]
+    }
+  }
 }
-EOF
-
-# Post it
-postiz posts:create --json post.json
 ```
 
-### Pattern 6: Multi-Platform Campaign
+---
 
-```javascript
-// AI Agent: Create coordinated multi-platform posts
-const campaign = {
-  type: "schedule",
-  date: "2024-12-25T12:00:00Z",
-  shortLink: true,
-  tags: [{ value: "campaign", label: "Campaign" }],
-  posts: [
-    {
-      integration: { id: "twitter-123" },
-      value: [{
-        content: "Twitter-optimized content 🐦",
-        image: [{ id: "t1", path: "twitter-image.jpg" }]
-      }]
-    },
-    {
-      integration: { id: "linkedin-456" },
-      value: [{
-        content: "Professional LinkedIn content 💼",
-        image: [{ id: "l1", path: "linkedin-image.jpg" }]
-      }]
-    },
-    {
-      integration: { id: "facebook-789" },
-      value: [
-        {
-          content: "Facebook main post 📱",
-          image: [{ id: "f1", path: "facebook-main.jpg" }]
-        },
-        {
-          content: "Additional context in comments",
-          image: [{ id: "f2", path: "facebook-comment.jpg" }],
-          delay: 300000  // 5 minutes later
-        }
-      ]
-    }
-  ]
-};
+## Technical Concepts
 
-require('fs').writeFileSync('campaign.json', JSON.stringify(campaign, null, 2));
-execSync('postiz posts:create --json campaign.json');
-```
+### Integration Tools Workflow
 
-### Pattern 7: Twitter Thread Creation
+Many integrations require dynamic data (IDs, tags, playlists) that can't be hardcoded. The tools workflow enables discovery and usage:
 
-```bash
-# Create a thread with multiple tweets, each with media
-postiz posts:create --json - << 'EOF'
+1. **Check available tools** - `integrations:settings` returns a `tools` array
+2. **Review tool schema** - Each tool has `methodName`, `description`, and `dataSchema`
+3. **Trigger tool** - Call `integrations:trigger` with required parameters
+4. **Use output** - Tool returns data to use in post settings
+
+**Example tools by platform:**
+- **Reddit**: `getFlairs`, `searchSubreddits`, `getSubreddits`
+- **YouTube**: `getPlaylists`, `getCategories`, `getChannels`
+- **LinkedIn**: `getCompanies`, `getOrganizations`
+- **Twitter/X**: `getListsowned`, `getCommunities`
+- **Pinterest**: `getBoards`, `getBoardSections`
+
+### Provider Settings Structure
+
+Platform-specific settings use a discriminator pattern with `__type` field:
+
+```json
 {
-  "type": "now",
-  "date": "2024-01-15T12:00:00Z",
-  "shortLink": true,
-  "tags": [],
-  "posts": [{
-    "integration": { "id": "twitter-123" },
-    "value": [
-      {
-        "content": "🧵 Thread about X (1/3)",
-        "image": [{ "id": "1", "path": "https://example.com/thread-1.jpg" }]
-      },
-      {
-        "content": "Key point number 1 (2/3)",
-        "image": [{ "id": "2", "path": "https://example.com/thread-2.jpg" }],
-        "delay": 2000
-      },
-      {
-        "content": "Conclusion and CTA (3/3)",
-        "image": [{ "id": "3", "path": "https://example.com/thread-3.jpg" }],
-        "delay": 2000
+  "posts": [
+    {
+      "provider": "reddit",
+      "post": [{ "content": "...", "image": [...] }],
+      "settings": {
+        "__type": "reddit",
+        "subreddit": [{
+          "value": {
+            "subreddit": "programming",
+            "title": "Post Title",
+            "type": "text",
+            "url": "",
+            "is_flair_required": false
+          }
+        }]
       }
-    ],
-    "settings": { "__type": "EmptySettings" }
-  }]
+    }
+  ]
 }
-EOF
 ```
 
-### Pattern 8: Upload Media, Then Post
+Pass settings directly:
+```bash
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" --settings '{"subreddit":[...]}' -i "reddit-id"
+# Backend automatically adds "__type" based on integration ID
+```
 
+### Comments and Threading
+
+Posts can have comments (threads on Twitter/X, replies elsewhere). Each comment can have its own media:
+
 ```bash
-# 1. Upload images first
-IMG1=$(postiz upload ./image1.jpg | jq -r '.path')
-IMG2=$(postiz upload ./image2.jpg | jq -r '.path')
+# Using multiple -c and -m flags
+postiz posts:create \
+  -c "Main post" -m "image1.jpg,image2.jpg" \
+  -c "Comment 1" -m "comment-img.jpg" \
+  -c "Comment 2" -m "another.jpg,more.jpg" \
+  -s "2024-12-31T12:00:00Z" \
+  -d 5000 \  # Delay between comments in ms
+  -i "integration-id"
+```
 
-# 2. Create post with uploaded images
-cat > post.json << EOF
+Internally creates:
+```json
 {
-  "type": "now",
-  "date": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
-  "shortLink": true,
-  "tags": [],
   "posts": [{
-    "integration": { "id": "twitter-123" },
-    "value": [{
-      "content": "Check out these images!",
-      "image": [
-        { "id": "img1", "path": "$IMG1" },
-        { "id": "img2", "path": "$IMG2" }
-      ]
-    }],
-    "settings": { "__type": "EmptySettings" }
+    "value": [
+      { "content": "Main post", "image": ["image1.jpg", "image2.jpg"] },
+      { "content": "Comment 1", "image": ["comment-img.jpg"], "delay": 5000 },
+      { "content": "Comment 2", "image": ["another.jpg", "more.jpg"], "delay": 5000 }
+    ]
   }]
 }
-EOF
-
-postiz posts:create --json post.json
 ```
 
-## Output Format
+### Date Handling
 
-All commands return JSON output, making it easy for AI agents to parse and process results:
+All dates use ISO 8601 format:
+- Schedule posts: `-s "2024-12-31T12:00:00Z"`
+- List posts: `--startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"`
+- Defaults: `posts:list` uses 30 days ago to 30 days from now
 
+### Media Upload Response
+
+Upload returns JSON with path and metadata:
 ```json
 {
-  "success": true,
-  "data": {
-    "id": "post-123",
-    "content": "Hello World!",
-    "scheduledDate": "2024-01-15T12:00:00Z"
-  }
+  "path": "https://cdn.postiz.com/uploads/abc123.jpg",
+  "size": 123456,
+  "type": "image/jpeg"
 }
 ```
 
-## Error Handling
+Extract path for use in posts:
+```bash
+RESULT=$(postiz upload image.jpg)
+PATH=$(echo "$RESULT" | jq -r '.path')
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -m "$PATH" -i "integration-id"
+```
 
-The CLI provides clear error messages:
+### JSON Mode vs CLI Flags
 
-- Missing API key: `❌ Error: POSTIZ_API_KEY environment variable is required`
-- API errors: `❌ API Error (status): message`
-- File not found: `❌ Failed to upload file: message`
+**CLI flags** - Quick posts:
+```bash
+postiz posts:create -c "Content" -m "img.jpg" -i "twitter-id"
+```
 
-Exit codes:
-- `0`: Success
-- `1`: Error occurred
+**JSON mode** - Complex posts with multiple platforms and settings:
+```bash
+postiz posts:create --json post.json
+```
 
-## Environment Variables
+JSON mode supports:
+- Multiple platforms with different content per platform
+- Complex provider-specific settings
+- Scheduled posts
+- Posts with many comments
+- Custom delay between comments
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `POSTIZ_API_KEY` | Yes | - | Your Postiz API key |
-| `POSTIZ_API_URL` | No | `https://api.postiz.com` | Custom API endpoint |
+---
 
-## Tips for AI Agents
+## Platform-Specific Examples
 
-1. **Always set the API key** before running commands
-2. **Parse JSON output** using tools like `jq` for scripting
-3. **Check exit codes** to determine if commands succeeded
-4. **Use integrations:list** first to get valid integration IDs
-5. **Schedule posts** in the future using ISO 8601 date format
-6. **Upload media first** before referencing in posts
+### Reddit
+```bash
+postiz posts:create \
+  -c "Post content" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Title","type":"text","url":"","is_flair_required":false}}]}' \
+  -i "reddit-id"
+```
 
-## Example Workflow Script
+### YouTube
+```bash
+postiz posts:create \
+  -c "Video description" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"title":"Video Title","type":"public","tags":[{"value":"tech","label":"Tech"}]}' \
+  -m "video.mp4" \
+  -i "youtube-id"
+```
 
+### TikTok
 ```bash
-#!/bin/bash
+postiz posts:create \
+  -c "Video caption #fyp" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"privacy":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true}' \
+  -m "video.mp4" \
+  -i "tiktok-id"
+```
 
-# Set API key
-export POSTIZ_API_KEY="your-api-key-here"
+### X (Twitter)
+```bash
+postiz posts:create \
+  -c "Tweet content" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"who_can_reply_post":"everyone"}' \
+  -i "twitter-id"
+```
 
-# Get integrations
-INTEGRATIONS=$(postiz integrations:list)
-echo "Available integrations: $INTEGRATIONS"
+### LinkedIn
+```bash
+# Personal post
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "linkedin-id"
 
-# Create a post
+# Company post
 postiz posts:create \
-  -c "Automated post from AI agent" \
-  -s "2024-12-25T12:00:00Z" \
-  -i "twitter-123,linkedin-456"
+  -c "Content" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"companyId":"company-123"}' \
+  -i "linkedin-id"
+```
 
-# List all posts
-postiz posts:list -l 5
+### Instagram
+```bash
+# Regular post
+postiz posts:create \
+  -c "Caption #hashtag" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"post_type":"post"}' \
+  -m "image.jpg" \
+  -i "instagram-id"
 
-echo "✅ Workflow completed!"
+# Story
+postiz posts:create \
+  -c "" \
+  -s "2024-12-31T12:00:00Z" \
+  --settings '{"post_type":"story"}' \
+  -m "story.jpg" \
+  -i "instagram-id"
 ```
 
-## Support
+---
 
-For issues or questions:
-- GitHub: https://github.com/gitroomhq/postiz-app
-- Documentation: https://postiz.com/docs
-- API Reference: https://postiz.com/api-docs
+## Supporting Resources
+
+**Deep-dive documentation:**
+- [HOW_TO_RUN.md](./HOW_TO_RUN.md) - Installation and setup methods
+- [COMMAND_LINE_GUIDE.md](./COMMAND_LINE_GUIDE.md) - Complete command syntax reference
+- [PROVIDER_SETTINGS.md](./PROVIDER_SETTINGS.md) - All 28+ platform settings schemas
+- [INTEGRATION_TOOLS_WORKFLOW.md](./INTEGRATION_TOOLS_WORKFLOW.md) - Complete tools workflow guide
+- [INTEGRATION_SETTINGS_DISCOVERY.md](./INTEGRATION_SETTINGS_DISCOVERY.md) - Settings discovery workflow
+- [SUPPORTED_FILE_TYPES.md](./SUPPORTED_FILE_TYPES.md) - All supported media formats
+- [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) - Code architecture
+- [PUBLISHING.md](./PUBLISHING.md) - npm publishing guide
+
+**Ready-to-use examples:**
+- [examples/EXAMPLES.md](./examples/EXAMPLES.md) - Comprehensive examples
+- [examples/basic-usage.sh](./examples/basic-usage.sh) - Shell script basics
+- [examples/ai-agent-example.js](./examples/ai-agent-example.js) - Node.js agent
+- [examples/post-with-comments.json](./examples/post-with-comments.json) - Threading example
+- [examples/multi-platform-with-settings.json](./examples/multi-platform-with-settings.json) - Campaign example
+- [examples/youtube-video.json](./examples/youtube-video.json) - YouTube with tags
+- [examples/reddit-post.json](./examples/reddit-post.json) - Reddit with subreddit
+- [examples/tiktok-video.json](./examples/tiktok-video.json) - TikTok with privacy
+
+---
+
+## Common Gotchas
+
+1. **API Key not set** - Always `export POSTIZ_API_KEY=key` before using CLI
+2. **Invalid integration ID** - Run `integrations:list` to get current IDs
+3. **Settings schema mismatch** - Check `integrations:settings` for required fields
+4. **Media upload before posting** - Upload returns URL to use in `-m` flag
+5. **JSON escaping in shell** - Use single quotes for JSON: `--settings '{...}'`
+6. **Date format** - Must be ISO 8601: `"2024-12-31T12:00:00Z"`
+7. **Tool not found** - Check available tools in `integrations:settings` output
+8. **Character limits** - Each platform has different limits, check `maxLength` in settings
+9. **Required settings** - Some platforms require specific settings (Reddit needs title, YouTube needs title)
+10. **Media MIME types** - CLI auto-detects from file extension, ensure correct extension
+
+---
+
+## Quick Reference
+
+```bash
+# Environment
+export POSTIZ_API_KEY=key
+
+# Discovery
+postiz integrations:list                           # Get integration IDs
+postiz integrations:settings <id>                  # Get settings schema
+postiz integrations:trigger <id> <method> -d '{}'  # Fetch dynamic data
+
+# Posting (date is REQUIRED)
+postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" -i "id"                  # Simple
+postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" -t draft -i "id"        # Draft
+postiz posts:create -c "text" -m "img.jpg" -s "2024-12-31T12:00:00Z" -i "id"    # With media
+postiz posts:create -c "main" -c "comment" -s "2024-12-31T12:00:00Z" -i "id"    # With comment
+postiz posts:create -c "text" -s "2024-12-31T12:00:00Z" --settings '{}' -i "id" # Platform-specific
+postiz posts:create --json file.json                                             # Complex
+
+# Management
+postiz posts:list                                  # List posts
+postiz posts:delete <id>                          # Delete post
+postiz upload <file>                              # Upload media
+
+# Help
+postiz --help                                     # Show help
+postiz posts:create --help                        # Command help
+```

New alerts

Network access

Supply chain risk

This module accesses the network.

Found 4 instances in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 4 instances in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

Network access

Supply chain risk

This module accesses the network.

Found 4 instances in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 4 instances in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1537251

0.9%

Number of lines in readme file

611

89.75%

Worsened metrics

Lines of code

12756

-0.03%

No dependency changes