From dc8a380176c66073807669fd9aeb7eec6d28754f Mon Sep 17 00:00:00 2001 From: Nevo David Date: Sat, 14 Feb 2026 11:57:12 +0700 Subject: [PATCH] feat: README and SKILL --- apps/cli/README.md | 47 +++++++++++++++++++++++++++++++++++++++------- apps/cli/SKILL.md | 34 +++++++++++++++++++++++++++------ 2 files changed, 68 insertions(+), 13 deletions(-) diff --git a/apps/cli/README.md b/apps/cli/README.md index 31c86fc0..1c7983d8 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -180,6 +180,15 @@ postiz posts:delete postiz upload ``` +**⚠️ 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 +197,19 @@ postiz upload **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 +232,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 +294,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" ``` diff --git a/apps/cli/SKILL.md b/apps/cli/SKILL.md index ba272887..fea39a91 100644 --- a/apps/cli/SKILL.md +++ b/apps/cli/SKILL.md @@ -107,12 +107,19 @@ postiz posts:delete ### 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)