postiz 2.0.5 → 2.0.6

package/README.md

@@ -29,7 +29,6 @@ pnpm link --global
 ### For Development
 
 ```bash
-cd apps/cli
 pnpm install
 pnpm run build
 pnpm link --global
@@ -180,6 +179,15 @@ postiz posts:delete <post-id>
 postiz upload <file-path>
 ```
 
+**⚠️ IMPORTANT: Upload Files Before Posting**
+
+You **must** upload media files to Postiz before using them in posts. Many platforms (especially TikTok, Instagram, and YouTube) require verified/trusted URLs and will reject external links.
+
+**Workflow:**
+1. Upload your file using `postiz upload`
+2. Extract the returned URL
+3. Use that URL in your post's `-m` parameter
+
 **Supported formats:**
 - **Images:** PNG, JPG, JPEG, GIF, WEBP, SVG, BMP, ICO
 - **Videos:** MP4, MOV, AVI, MKV, WEBM, FLV, WMV, M4V, MPEG, MPG, 3GP
@@ -188,11 +196,19 @@ postiz upload <file-path>
 
 **Example:**
 ```bash
+# 1. Upload the file first
 RESULT=$(postiz upload video.mp4)
 PATH=$(echo "$RESULT" | jq -r '.path')
-postiz posts:create -c "Check out my video!" -m "$PATH" -i "tiktok-id"
+
+# 2. Use the Postiz URL in your post
+postiz posts:create -c "Check out my video!" -s "2024-12-31T12:00:00Z" -m "$PATH" -i "tiktok-id"
 ```
 
+**Why this is required:**
+- **TikTok, Instagram, YouTube** only accept URLs from trusted domains
+- **Security:** Platforms verify media sources to prevent abuse
+- **Reliability:** Postiz ensures your media is always accessible
+
 ---
 
 ## Platform-Specific Features
@@ -215,22 +231,31 @@ postiz posts:create \
 # Get playlists
 postiz integrations:trigger youtube-id getPlaylists
 
-# Upload video with metadata
+# Upload video FIRST (required!)
+VIDEO=$(postiz upload video.mp4)
+VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
+
+# Post with uploaded video URL
 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" \
+  -m "$VIDEO_URL" \
   -i "youtube-id"
 ```
 
 ### TikTok
 ```bash
+# Upload video FIRST (TikTok only accepts verified URLs!)
+VIDEO=$(postiz upload video.mp4)
+VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
+
+# Post with uploaded video URL
 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" \
+  -m "$VIDEO_URL" \
   -i "tiktok-id"
 ```
 
@@ -268,20 +293,27 @@ postiz posts:create \
 
 ### Instagram
 ```bash
+# Upload image FIRST (Instagram requires verified URLs!)
+IMAGE=$(postiz upload image.jpg)
+IMAGE_URL=$(echo "$IMAGE" | jq -r '.path')
+
 # Regular post
 postiz posts:create \
   -c "Caption #hashtag" \
   -s "2024-12-31T12:00:00Z" \
   --settings '{"post_type":"post"}' \
-  -m "image.jpg" \
+  -m "$IMAGE_URL" \
   -i "instagram-id"
 
-# Story
+# Story (upload first)
+STORY=$(postiz upload story.jpg)
+STORY_URL=$(echo "$STORY" | jq -r '.path')
+
 postiz posts:create \
   -c "" \
   -s "2024-12-31T12:00:00Z" \
   --settings '{"post_type":"story"}' \
-  -m "story.jpg" \
+  -m "$STORY_URL" \
   -i "instagram-id"
 ```
 
@@ -491,21 +523,20 @@ The CLI provides clear error messages with exit codes:
 ### Project Structure
 
 ```
-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
+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
 ```
 
 ### Scripts

package/SKILL.md

@@ -107,12 +107,19 @@ postiz posts:delete <post-id>
 
 ### Media Upload
 
+**⚠️ IMPORTANT:** Always upload files to Postiz before using them in posts. Many platforms (TikTok, Instagram, YouTube) **require verified URLs** and will reject external links.
+
 ```bash
 # Upload file and get URL
 postiz upload image.jpg
 
 # Supports: images (PNG, JPG, GIF, WEBP, SVG), videos (MP4, MOV, AVI, MKV, WEBM),
 # audio (MP3, WAV, OGG, AAC), documents (PDF, DOC, DOCX)
+
+# Workflow: Upload → Extract URL → Use in post
+VIDEO=$(postiz upload video.mp4)
+VIDEO_PATH=$(echo "$VIDEO" | jq -r '.path')
+postiz posts:create -c "Content" -s "2024-12-31T12:00:00Z" -m "$VIDEO_PATH" -i "tiktok-id"
 ```
 
 ---
@@ -455,21 +462,29 @@ postiz posts:create \
 
 ### YouTube
 ```bash
+# Upload video first (required!)
+VIDEO=$(postiz upload video.mp4)
+VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
+
 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" \
+  -m "$VIDEO_URL" \
   -i "youtube-id"
 ```
 
 ### TikTok
 ```bash
+# Upload video first (TikTok only accepts verified URLs!)
+VIDEO=$(postiz upload video.mp4)
+VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')
+
 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" \
+  -m "$VIDEO_URL" \
   -i "tiktok-id"
 ```
 
@@ -497,20 +512,27 @@ postiz posts:create \
 
 ### Instagram
 ```bash
+# Upload image first (Instagram requires verified URLs!)
+IMAGE=$(postiz upload image.jpg)
+IMAGE_URL=$(echo "$IMAGE" | jq -r '.path')
+
 # Regular post
 postiz posts:create \
   -c "Caption #hashtag" \
   -s "2024-12-31T12:00:00Z" \
   --settings '{"post_type":"post"}' \
-  -m "image.jpg" \
+  -m "$IMAGE_URL" \
   -i "instagram-id"
 
 # Story
+STORY=$(postiz upload story.jpg)
+STORY_URL=$(echo "$STORY" | jq -r '.path')
+
 postiz posts:create \
   -c "" \
   -s "2024-12-31T12:00:00Z" \
   --settings '{"post_type":"story"}' \
-  -m "story.jpg" \
+  -m "$STORY_URL" \
   -i "instagram-id"
 ```
 
@@ -545,9 +567,9 @@ postiz posts:create \
 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
+4. **Media MUST be uploaded to Postiz first** - ⚠️ **CRITICAL:** TikTok, Instagram, YouTube, and many platforms only accept verified URLs. Upload files via `postiz upload` first, then use the returned URL in `-m`. External URLs will be rejected!
 5. **JSON escaping in shell** - Use single quotes for JSON: `--settings '{...}'`
-6. **Date format** - Must be ISO 8601: `"2024-12-31T12:00:00Z"`
+6. **Date format** - Must be ISO 8601: `"2024-12-31T12:00:00Z"` and is REQUIRED
 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)