Compose Action - URL Scheme Guide

Open the Statuz composer with optional pre-filled content. The composer provides the full Statuz interface for selecting platforms, accounts, and editing before publishing.

Syntax

statuz://compose[?parameters]

Parameters

ParameterTypeDescriptionExample
textstringPost content (URL-encoded)Hello%20World
mediastringComma-separated file paths or URLsfile:///path/img.png,https://example.com/img.jpg
filesstringAlias for media when passing raw absolute paths/Users/me/Desktop/photo.png,/tmp/video.mov
bkstringBase64 security-scoped bookmarks (comma-separated)AAAA...=,BBBB...=
pbstringPasteboard token for reading bookmarks/payloadSTATUZ_PB_TOKEN
scheduleISO8601Schedule date/time2024-12-25T10:00:00Z
timezonestringTimezone identifier (IANA format)America/New_York
quotestringURL or ID of post to quotehttps://x.com/user/status/123
threadbooleanCreate multi-post threadtrue
autosplitbooleanAuto-split long text into threadtrue
draftbooleanSave as draft instead of publishingtrue

Note: Platform and account selection happens in the Statuz UI. The URL scheme pre-fills content, then you choose where to publish using the app's interface.

Examples

Basic Post

Create a simple post:

open "statuz://compose?text=Hello%20from%20automation!"

Post with Image

Attach a local image:

open "statuz://compose?text=Check%20this%20out!&media=file:///Users/me/Desktop/screenshot.png"

Post with Remote Image

Automatically download and attach a remote image:

open "statuz://compose?text=Amazing%20photo!&media=https://example.com/photo.jpg"

Multiple Images

Attach multiple images (comma-separated):

TEXT="Here are the results"
MEDIA="file:///path/to/chart1.png,file:///path/to/chart2.png,file:///path/to/chart3.png"
ENCODED_TEXT=$(echo "$TEXT" | jq -sRr @uri)
ENCODED_MEDIA=$(echo "$MEDIA" | jq -sRr @uri)
open "statuz://compose?text=$ENCODED_TEXT&media=$ENCODED_MEDIA"

Schedule at Specific Time

Pre-fill with scheduled time:

open "statuz://compose?text=Good%20morning!&schedule=2024-12-25T09:00:00Z&timezone=America/New_York"

Quote Tweet

Quote an existing tweet:

open "statuz://compose?text=Great%20insight!&quote=https://x.com/user/status/123456789"

Create Thread

Create a multi-post thread:

TEXT="Post 1 content

Post 2 content

Post 3 content"
ENCODED=$(echo "$TEXT" | jq -sRr @uri)
open "statuz://compose?text=$ENCODED&thread=true"

Auto-Split Long Post

Automatically split long text into multiple posts:

LONG_TEXT="This is a very long post that exceeds the character limit. It will be automatically split into multiple posts to fit within the platform's constraints. Each post will be properly formatted and linked as a thread."
ENCODED=$(echo "$LONG_TEXT" | jq -sRr @uri)
open "statuz://compose?text=$ENCODED&autosplit=true"

Save as Draft

Open composer and save as draft:

open "statuz://compose?text=Work%20in%20progress...&draft=true"

File Attachment Methods

macOS sandbox requires special handling for file access. Statuz provides four methods:

1. Direct Paths (Recommended for Scripts)

Use file:// URLs or absolute paths. On first access from a new directory, Statuz prompts once to grant access:

open "statuz://compose?media=file:///Users/me/Desktop/photo.jpg"
Supports:

• Absolute paths with file:// prefix

• Paths with spaces (no escaping needed)

• Tilde expansion: ~/Desktop/photo.jpg

• Multiple files: comma-separated

2. Security-Scoped Bookmarks (Advanced)

For silent operation without prompts, use pre-generated bookmarks:

# Generate bookmark (requires Statuz helper tool)
BOOKMARK=$(statuz-bookmark create ~/Desktop/photo.jpg)

# Use in URL scheme
open "statuz://compose?bk=$BOOKMARK"

3. Pasteboard Bridge (For Complex Integrations)

Write bookmarks or file data to a named pasteboard:

# Create pasteboard with bookmarks
TOKEN="STATUZ_$(uuidgen)"
pbcopy -pboard "$TOKEN" <<EOF
{
 "bookmarks": ["<BASE64_BOOKMARK_1>", "<BASE64_BOOKMARK_2>"]
}
EOF

open "statuz://compose?pb=$TOKEN"

Or with embedded file data:

TOKEN="STATUZ_$(uuidgen)"
pbcopy -pboard "$TOKEN" <<EOF
{
 "items": [
 {
 "name": "photo.png",
 "data": "<BASE64_FILE_DATA>"
 }
 ]
}
EOF

open "statuz://compose?pb=$TOKEN"

4. Remote URLs (Simplest for Online Media)

Download files automatically from HTTP/HTTPS URLs:

open "statuz://compose?media=https://example.com/image.jpg,https://example.com/video.mp4"
Supported formats:

• Images: PNG, JPG, GIF

• Videos: MP4, MOV

Limits:

• Maximum 4 attachments per post

• Files must be within platform size limits

• Remote downloads require active internet connection

Advanced Examples

Screenshot Automation

#!/bin/bash
# Take screenshot and open in Statuz
screencapture -i /tmp/screenshot.png
TEXT="Check out this screenshot!"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://compose?text=$ENCODED&media=file:///tmp/screenshot.png"

Clipboard Sharing

#!/bin/bash
# Post clipboard content
CLIPBOARD=$(pbpaste)
ENCODED=$(printf %s "$CLIPBOARD" | jq -sRr @uri)
open "statuz://compose?text=$ENCODED"

Daily Report Automation

#!/bin/bash
# Generate and post daily report
REPORT="Daily Update - $(date +%Y-%m-%d)

✅ Tasks completed: 8
⏳ In progress: 3
🎯 On track for goals"

ENCODED=$(printf %s "$REPORT" | jq -sRr @uri)
open "statuz://compose?text=$ENCODED"

Thread from File

#!/bin/bash
# Create thread from text file (one paragraph per post)
CONTENT=$(cat report.txt)
ENCODED=$(printf %s "$CONTENT" | jq -sRr @uri)
open "statuz://compose?text=$ENCODED&thread=true"

Integration Examples

Apple Shortcuts

Create a Shortcut with these actions:

• Get Clipboard

• URL Encode clipboard content

• Open URL: statuz://compose?text=[encoded]

Raycast Script Command

#!/usr/bin/env node
// @raycast.schemaVersion 1
// @raycast.title Post to Statuz
// @raycast.mode silent

const { exec } = require('child_process');
const text = process.argv.slice(2).join(' ');
const encoded = encodeURIComponent(text);
exec(`open "statuz://compose?text=${encoded}"`);

Alfred Workflow

• Create Keyword trigger: post

• Add Run Script action:

query="{query}"
encoded=$(printf %s "$query" | jq -sRr @uri)
open "statuz://compose?text=$encoded"

Keyboard Maestro Macro

• Create new macro with hotkey

• Add Execute Shell Script action:

TEXT="Your post content"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://compose?text=$ENCODED"

Error Handling

The compose action will show user-friendly errors for:

• Invalid media files - File not found or unsupported format

• Too many attachments - Maximum 4 media items per post

• Invalid date format - Schedule date must be ISO 8601

• Invalid quote URL - Quote URL must be a valid post URL

• File access denied - User declined folder access permission

Platform Behavior

X (Twitter)

• Character limit: 280 characters

• Media: Up to 4 images or 1 video

• Threads: Up to 25 posts per thread

BlueSky

• Character limit: 300 characters

• Media: Up to 4 images or 1 video

• Threads: Unlimited posts

Mastodon

• Character limit: 500 characters (instance-dependent)

• Media: Up to 4 images or 1 video

• File size limit: 40MB (instance-dependent)

• Threads: Unlimited posts

Tips

• Always URL-encode text parameters to handle special characters

• Use file:// prefix for local media paths

• Test with small files first when using remote URLs

• Check platform limits before attaching multiple large files

• Use drafts for complex posts that need manual review

Related

• Schedule Action (/docs/url-scheme-schedule) - Schedule posts for later

• Scheduled Action (/docs/url-scheme-scheduled) - Edit scheduled posts

• Examples (/docs/url-scheme-examples) - More code examples

Try Statuz today,
it's free.
Download for macOS (/download)