zernio-cli 0.4.1 → 0.5.0

package/README.md

@@ -61,6 +61,17 @@ zernio posts:create \
   --media "https://public-url-from-upload" \
   --scheduledAt "2026-06-20T09:00:00Z"
 
+# Native X/Twitter quote, reply, and thread options
+zernio posts:create \
+  --text "Thread display title" \
+  --accounts <twitterAccountId> \
+  --threadJson '["tweet 1","tweet 2"]'
+
+zernio posts:create \
+  --text "my take" \
+  --accounts <twitterAccountId> \
+  --quoteTweetId "https://x.com/user/status/2061975910467698972"
+
 # Queue scheduling: let Zernio assign the slot
 zernio api:call createPost \
   --body-json '{"content":"Queued post","platforms":[{"platform":"twitter","accountId":"acc_123"}],"queuedFromProfile":"profile_123"}'
@@ -118,7 +129,8 @@ For media uploads, prefer `zernio media:upload`; it implements the official pres
 - Respect `Retry-After` and `X-RateLimit-*` headers.
 - Use `--request-id` or `--idempotency-key` for mutating calls that document safe retry headers.
 - Use pagination, caching, webhooks, and bulk endpoints for automation.
-- Use `platformSpecificData` for per-platform post settings.
+- Use `platformSpecificData` for per-platform post settings. `posts:create` wraps common X/Twitter fields with `--quoteTweetId`, `--replyToTweetId`, `--replySettings`, `--threadJson`, `--threadFile`, and `--platformSpecificData`.
+- For failed `posts:create` calls, use `--debug-safe` to print non-secret account/platform diagnostics.
 - Check current platform support at https://docs.zernio.com/platforms instead of relying on a fixed count.
 
 ## Development

package/claude/skills/zernio/SKILL.md

@@ -52,6 +52,8 @@ zernio accounts:list --pretty
 zernio accounts:health --pretty
 zernio media:upload ./photo.jpg --pretty
 zernio posts:create --text "Hello" --accounts <accountId>
+zernio posts:create --text "Thread title" --accounts <twitterAccountId> --threadFile ./thread.txt
+zernio posts:create --text "my take" --accounts <twitterAccountId> --quoteTweetId <tweetId-or-url>
 zernio inbox:conversations --platform instagram --pretty
 zernio contacts:list --search "john" --pretty
 zernio broadcasts:list --status draft --pretty
@@ -76,6 +78,8 @@ zernio api:call createPost --body-file ./post.json --request-id req_123 --pretty
 - Use `--request-id` or `--idempotency-key` for mutating endpoints that document safe retry headers.
 - For queue scheduling, let Zernio assign the slot with `queuedFromProfile` and optional `queueId`.
 - For media, use `media:upload`; it performs presign + direct PUT.
+- For native X/Twitter posts, use `posts:create --threadJson`, `--threadFile`, `--quoteTweetId`, `--replyToTweetId`, `--replySettings`, or `--platformSpecificData` before dropping down to raw `api:call`.
+- For confusing `posts:create` failures, retry with `--debug-safe --pretty` and report only the non-secret diagnostics.
 - For current platform details, consult https://docs.zernio.com/platforms instead of relying on a fixed count.
 
 ## References

package/claude/skills/zernio/references/zernio-api-surface.md

@@ -1,6 +1,6 @@
 # Zernio Command Surface
 
-Current target: `zernio-cli` 0.4.0. JSON is default; add `--pretty` for humans.
+Current target: `zernio-cli` 0.4.1+. JSON is default; add `--pretty` for humans.
 
 ## Agent/system commands
 
@@ -35,7 +35,8 @@ Use profile/account IDs from these commands before posting, inbox, broadcasts, s
 
 | Use case | Commands |
 | --- | --- |
-| Create/publish/schedule/draft | `posts:create --text <text> --accounts <ids> [--scheduledAt --draft --media --title --tags --hashtags --timezone]` |
+| Create/publish/schedule/draft | `posts:create --text <text> --accounts <ids> [--scheduledAt --draft --media --title --tags --hashtags --timezone --debug-safe]` |
+| Native X/Twitter post options | `posts:create --accounts <twitterId> --text <display> [--quoteTweetId --replyToTweetId --replySettings --threadJson --threadFile --platformSpecificData]` |
 | Post lifecycle | `posts:list [--profileId --status --platform --from --to --page --limit]`, `posts:get <id>`, `posts:delete <id>`, `posts:retry <id>` |
 | Analytics | `analytics:posts [--profileId --platform --postId --source --from --to --sortBy --order --page --limit]`, `analytics:daily [--profileId --platform --from --to]`, `analytics:best-time [--profileId --platform]` |
 | Media upload | `media:upload <file>` |

package/claude/skills/zernio/references/zernio-best-practices.md

@@ -28,6 +28,7 @@
 ## Error Handling
 
 - Treat `401/403` as auth/scope issues; run `doctor --connection` and verify profile/account access.
+- For `posts:create` failures, rerun with `--debug-safe --pretty` to include non-secret platform/account context and recovery hints.
 - Treat `404` as wrong ID or missing scope; rediscover IDs with list/get commands.
 - Treat `409` as state conflict; refresh resource state before retrying.
 - Treat `422` as payload/schema issue; run `api:describe` and inspect request body.
@@ -64,6 +65,9 @@
 
 - Use `platforms:list` for identifiers; use `https://docs.zernio.com/platforms` as current capability source.
 - Use `platformSpecificData` in OpenAPI payloads for per-platform fields.
+- For X/Twitter, curated `posts:create` supports `--quoteTweetId`, `--replyToTweetId`, `--replySettings`, `--threadJson`, `--threadFile`, and `--platformSpecificData`.
+- For X/Twitter threads, top-level `--text` is only for Zernio display/search; include the root tweet in `threadItems[0]`.
+- Do not mix X-specific `posts:create` options with non-X accounts. Do not combine `quoteTweetId` with top-level `--media`, or `replyToTweetId` with `replySettings`.
 - Require title where platform needs it, especially YouTube, Reddit, Pinterest-style content.
 - Check media and character constraints before posting multi-platform content.
 - Do not assume platform support count is static; current CLI includes twitter, instagram, facebook, linkedin, tiktok, youtube, pinterest, reddit, bluesky, threads, googlebusiness, telegram, snapchat, whatsapp, discord.

package/claude/skills/zernio/references/zernio-workflows.md

@@ -63,6 +63,42 @@ Draft:
 zernio posts:create --text "Draft copy" --accounts <accountId> --draft
 ```
 
+Native X/Twitter thread:
+
+```bash
+zernio posts:create \
+  --text "Thread display title" \
+  --accounts <twitterAccountId> \
+  --threadJson '["tweet 1","tweet 2","tweet 3"]'
+```
+
+Thread from file:
+
+```bash
+zernio posts:create \
+  --text "Thread display title" \
+  --accounts <twitterAccountId> \
+  --threadFile ./thread.txt
+```
+
+`thread.txt` can be a JSON array or plain text separated by lines containing only `---`. When thread items are present, `--text` is only for Zernio display/search; put the first published tweet in `threadItems[0]`.
+
+Native X/Twitter quote or reply:
+
+```bash
+zernio posts:create \
+  --text "my take" \
+  --accounts <twitterAccountId> \
+  --quoteTweetId "https://x.com/user/status/2061975910467698972"
+
+zernio posts:create \
+  --text "reply text" \
+  --accounts <twitterAccountId> \
+  --replyToTweetId "2061975910467698972"
+```
+
+Use `--platformSpecificData '{"replySettings":"following"}'` for advanced X passthrough. X-specific options require only `twitter`/`x` targets.
+
 Track/retry:
 
 ```bash
@@ -71,6 +107,12 @@ zernio posts:get <postId> --pretty
 zernio posts:retry <postId> --pretty
 ```
 
+Debug failed post creation without exposing secrets:
+
+```bash
+zernio posts:create --text "Draft copy" --accounts <accountId> --draft --debug-safe --pretty
+```
+
 ## Upload Media Then Post
 
 ```bash

package/dist/commands/posts-create.d.ts

@@ -0,0 +1,2 @@
+import type { Argv } from 'yargs';
+export declare function registerPostCreateCommand(yargs: Argv): Argv;

package/dist/commands/posts-create.js

@@ -0,0 +1,110 @@
+import { createClient } from '../client.js';
+import { addAccountHealthDiagnostics, handlePostCreateError } from '../utils/posts-create-diagnostics.js';
+import { applyTwitterPlatformSpecificData, buildMediaItems, buildTwitterPlatformSpecificData, PostsCreateValidationError, validateTwitterPlatformSpecificData, } from '../utils/posts-create-platform-data.js';
+import { output, outputError } from '../utils/output.js';
+export function registerPostCreateCommand(yargs) {
+    return yargs.command('posts:create', 'Create or schedule a post', (y) => y
+        .option('text', { type: 'string', describe: 'Post content text', demandOption: true })
+        .option('accounts', { type: 'string', describe: 'Comma-separated account IDs', demandOption: true })
+        .option('scheduledAt', { type: 'string', describe: 'ISO 8601 date to schedule (omit to publish now)' })
+        .option('draft', { type: 'boolean', describe: 'Save as draft', default: false })
+        .option('media', { type: 'string', describe: 'Comma-separated media URLs' })
+        .option('title', { type: 'string', describe: 'Post title (YouTube, Reddit, etc.)' })
+        .option('tags', { type: 'string', describe: 'Comma-separated tags' })
+        .option('hashtags', { type: 'string', describe: 'Comma-separated hashtags' })
+        .option('timezone', { type: 'string', describe: 'Timezone (e.g. America/New_York)' })
+        .option('quoteTweetId', { type: 'string', describe: 'X/Twitter tweet ID or status URL to quote' })
+        .option('replyToTweetId', { type: 'string', describe: 'X/Twitter tweet ID to reply to' })
+        .option('replySettings', {
+        type: 'string',
+        describe: 'X/Twitter reply settings: following, mentionedUsers, subscribers, verified',
+    })
+        .option('threadJson', { type: 'string', describe: 'X/Twitter threadItems as a JSON array' })
+        .option('threadFile', { type: 'string', describe: 'X/Twitter thread file, JSON array or --- separated text' })
+        .option('platformSpecificData', {
+        type: 'string',
+        describe: 'Advanced platformSpecificData JSON object for X/Twitter targets',
+    })
+        .option('debug-safe', {
+        type: 'boolean',
+        describe: 'Include non-secret post/account diagnostics when create fails',
+        default: false,
+    }), async (argv) => {
+        let platforms = [];
+        let selectedAccounts = [];
+        try {
+            const late = createClient();
+            const { data: accountsData } = await late.accounts.listAccounts();
+            const accountIds = argv.accounts.split(',').map((s) => s.trim()).filter(Boolean);
+            const allAccounts = accountsData?.accounts || [];
+            selectedAccounts = accountIds.map((id) => {
+                const account = allAccounts.find((a) => (a._id || a.id) === id);
+                if (!account) {
+                    throw new PostsCreateValidationError(`Account ${id} not found. Run "zernio accounts:list" to see available accounts.`, 'ACCOUNT_NOT_FOUND', 404);
+                }
+                return account;
+            });
+            platforms = selectedAccounts.map((account, index) => ({
+                platform: String(account.platform),
+                accountId: accountIds[index],
+            }));
+            const mediaItems = buildMediaItems(argv.media);
+            const twitterData = buildTwitterPlatformSpecificData({
+                quoteTweetId: argv.quoteTweetId,
+                replyToTweetId: argv.replyToTweetId,
+                replySettings: argv.replySettings,
+                threadJson: argv.threadJson,
+                threadFile: argv.threadFile,
+                platformSpecificData: argv.platformSpecificData,
+            });
+            validateTwitterPlatformSpecificData(twitterData, platforms, mediaItems);
+            platforms = applyTwitterPlatformSpecificData(platforms, twitterData);
+            if (argv.debugSafe) {
+                selectedAccounts = await addAccountHealthDiagnostics(late, accountIds, selectedAccounts);
+            }
+            const body = buildCreatePostBody(argv, platforms, mediaItems);
+            const { data } = await late.posts.createPost({ body });
+            output(data, argv.pretty);
+        }
+        catch (err) {
+            if (err instanceof PostsCreateValidationError) {
+                outputError(err.message, err.status, { code: err.code }, argv.pretty);
+            }
+            handlePostCreateError(err, {
+                debugSafe: argv.debugSafe,
+                pretty: argv.pretty,
+                platforms,
+                accounts: selectedAccounts,
+            });
+        }
+    });
+}
+function buildCreatePostBody(argv, platforms, mediaItems) {
+    const body = {
+        content: argv.text,
+        platforms,
+    };
+    if (mediaItems?.length)
+        body.mediaItems = mediaItems;
+    if (argv.title)
+        body.title = argv.title;
+    if (argv.timezone)
+        body.timezone = argv.timezone;
+    if (argv.tags)
+        body.tags = csv(argv.tags);
+    if (argv.hashtags)
+        body.hashtags = csv(argv.hashtags);
+    if (argv.draft) {
+        body.isDraft = true;
+    }
+    else if (argv.scheduledAt) {
+        body.scheduledFor = argv.scheduledAt;
+    }
+    else {
+        body.publishNow = true;
+    }
+    return body;
+}
+function csv(value) {
+    return value.split(',').map((s) => s.trim()).filter(Boolean);
+}

package/dist/commands/posts.js

@@ -1,70 +1,10 @@
 import { createClient } from '../client.js';
-import { output, outputError } from '../utils/output.js';
+import { output } from '../utils/output.js';
 import { handleError } from '../utils/errors.js';
+import { registerPostCreateCommand } from './posts-create.js';
 /** Register post commands: posts:create, posts:list, posts:get, posts:delete, posts:retry */
 export function registerPostCommands(yargs) {
-    return yargs
-        .command('posts:create', 'Create or schedule a post', (y) => y
-        .option('text', { type: 'string', describe: 'Post content text', demandOption: true })
-        .option('accounts', { type: 'string', describe: 'Comma-separated account IDs', demandOption: true })
-        .option('scheduledAt', { type: 'string', describe: 'ISO 8601 date to schedule (omit to publish now)' })
-        .option('draft', { type: 'boolean', describe: 'Save as draft', default: false })
-        .option('media', { type: 'string', describe: 'Comma-separated media URLs' })
-        .option('title', { type: 'string', describe: 'Post title (YouTube, Reddit, etc.)' })
-        .option('tags', { type: 'string', describe: 'Comma-separated tags' })
-        .option('hashtags', { type: 'string', describe: 'Comma-separated hashtags' })
-        .option('timezone', { type: 'string', describe: 'Timezone (e.g. America/New_York)' }), async (argv) => {
-        try {
-            const late = createClient();
-            // Look up accounts to resolve platform types
-            const { data: accountsData } = await late.accounts.listAccounts();
-            const allAccounts = accountsData?.accounts || [];
-            const accountIds = argv.accounts.split(',').map((s) => s.trim()).filter(Boolean);
-            const platforms = accountIds.map((id) => {
-                const account = allAccounts.find((a) => (a._id || a.id) === id);
-                if (!account) {
-                    outputError(`Account ${id} not found. Run "late accounts:list" to see available accounts.`, 404);
-                }
-                return { platform: account.platform, accountId: id };
-            });
-            // Build media items
-            const mediaItems = argv.media
-                ? argv.media.split(',').map((url) => {
-                    const trimmed = url.trim();
-                    const isVideo = /\.(mp4|mov|avi|webm|m4v)$/i.test(trimmed);
-                    return { type: (isVideo ? 'video' : 'image'), url: trimmed };
-                })
-                : undefined;
-            const body = {
-                content: argv.text,
-                platforms,
-            };
-            if (mediaItems?.length)
-                body.mediaItems = mediaItems;
-            if (argv.title)
-                body.title = argv.title;
-            if (argv.timezone)
-                body.timezone = argv.timezone;
-            if (argv.tags)
-                body.tags = argv.tags.split(',').map((s) => s.trim());
-            if (argv.hashtags)
-                body.hashtags = argv.hashtags.split(',').map((s) => s.trim());
-            if (argv.draft) {
-                body.isDraft = true;
-            }
-            else if (argv.scheduledAt) {
-                body.scheduledFor = argv.scheduledAt;
-            }
-            else {
-                body.publishNow = true;
-            }
-            const { data } = await late.posts.createPost({ body });
-            output(data, argv.pretty);
-        }
-        catch (err) {
-            handleError(err);
-        }
-    })
+    return registerPostCreateCommand(yargs)
         .command('posts:list', 'List posts', (y) => y
         .option('profileId', { type: 'string', describe: 'Filter by profile ID' })
         .option('status', { type: 'string', describe: 'Filter by status (scheduled, published, failed, draft)' })

package/dist/utils/posts-create-diagnostics.d.ts

@@ -0,0 +1,22 @@
+import type { PlatformTarget } from './posts-create-platform-data.js';
+type AccountRecord = Record<string, unknown>;
+type PostCreateErrorContext = {
+    debugSafe: boolean;
+    pretty: boolean;
+    platforms: PlatformTarget[];
+    accounts: AccountRecord[];
+};
+export declare function handlePostCreateError(err: unknown, context: PostCreateErrorContext): never;
+export declare function buildPostCreateDiagnostic(context: PostCreateErrorContext, status?: number): Record<string, unknown>;
+export declare function addAccountHealthDiagnostics(late: {
+    accounts?: {
+        getAccountHealth?: (args: {
+            path: {
+                accountId: string;
+            };
+        }) => Promise<{
+            data: unknown;
+        }>;
+    };
+}, accountIds: string[], accounts: AccountRecord[]): Promise<AccountRecord[]>;
+export {};

package/dist/utils/posts-create-diagnostics.js

@@ -0,0 +1,83 @@
+import { LateApiError } from '@zernio/node';
+import { handleError } from './errors.js';
+import { outputError } from './output.js';
+const SAFE_ACCOUNT_FIELDS = [
+    'profileId',
+    'profileName',
+    'platform',
+    'username',
+    'displayName',
+    'status',
+    'canPost',
+    'tokenValid',
+    'needsReconnect',
+    'issues',
+];
+export function handlePostCreateError(err, context) {
+    if (!context.debugSafe)
+        handleError(err);
+    const status = err instanceof LateApiError ? err.statusCode : undefined;
+    const message = err instanceof Error ? err.message : String(err);
+    outputError(message, status, {
+        code: status === 401 ? 'POST_CREATE_UNAUTHORIZED' : 'POST_CREATE_FAILED',
+        diagnostic: buildPostCreateDiagnostic(context, status),
+    }, context.pretty);
+}
+export function buildPostCreateDiagnostic(context, status) {
+    return {
+        command: 'posts:create',
+        resolvedPlatforms: context.platforms,
+        targetAccounts: context.platforms.map((target) => summarizeAccount(target, context.accounts)),
+        suggestions: suggestionsForStatus(status),
+    };
+}
+export async function addAccountHealthDiagnostics(late, accountIds, accounts) {
+    if (!late.accounts?.getAccountHealth)
+        return accounts;
+    const healthEntries = await Promise.all(accountIds.map(async (id) => {
+        try {
+            const { data } = await late.accounts.getAccountHealth({ path: { accountId: id } });
+            return [id, data];
+        }
+        catch {
+            return [id, undefined];
+        }
+    }));
+    const healthById = new Map(healthEntries.filter((entry) => isRecord(entry[1])));
+    return accounts.map((account) => {
+        const id = accountId(account);
+        return id && healthById.has(id) ? { ...account, ...healthById.get(id) } : account;
+    });
+}
+function summarizeAccount(target, accounts) {
+    const account = accounts.find((candidate) => accountId(candidate) === target.accountId) || {};
+    const summary = {
+        accountId: target.accountId,
+        platform: target.platform,
+    };
+    for (const field of SAFE_ACCOUNT_FIELDS) {
+        if (account[field] !== undefined && field !== 'platform')
+            summary[field] = account[field];
+    }
+    return summary;
+}
+function accountId(account) {
+    const id = account.id || account._id || account.accountId;
+    return id === undefined ? undefined : String(id);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function suggestionsForStatus(status) {
+    if (status === 401) {
+        return [
+            'Run zernio auth:check --pretty to verify the API key.',
+            'Run zernio accounts:health --pretty and compare the target account status.',
+            'If health is valid but create still returns 401, reconnect the account or report a backend authorization mismatch.',
+        ];
+    }
+    return [
+        'Run zernio doctor --connection --pretty to verify API connectivity.',
+        'Run the same payload with zernio api:call createPost --dry-run to inspect request shape.',
+    ];
+}

package/dist/utils/posts-create-platform-data.d.ts

@@ -0,0 +1,27 @@
+export { PostsCreateValidationError } from './posts-create-validation-error.js';
+export type MediaItem = {
+    type: 'image' | 'video';
+    url: string;
+    [key: string]: unknown;
+};
+export type PlatformTarget = {
+    platform: string;
+    accountId: string;
+    platformSpecificData?: Record<string, unknown>;
+};
+export type TwitterPlatformSpecificDataResult = {
+    hasData: boolean;
+    data?: Record<string, unknown>;
+};
+type TwitterPlatformOptions = {
+    quoteTweetId?: unknown;
+    replyToTweetId?: unknown;
+    replySettings?: unknown;
+    threadJson?: unknown;
+    threadFile?: unknown;
+    platformSpecificData?: unknown;
+};
+export declare function buildMediaItems(media?: unknown): MediaItem[] | undefined;
+export declare function buildTwitterPlatformSpecificData(options: TwitterPlatformOptions): TwitterPlatformSpecificDataResult;
+export declare function validateTwitterPlatformSpecificData(result: TwitterPlatformSpecificDataResult, platforms: PlatformTarget[], mediaItems?: MediaItem[]): void;
+export declare function applyTwitterPlatformSpecificData(platforms: PlatformTarget[], result: TwitterPlatformSpecificDataResult): PlatformTarget[];

package/dist/utils/posts-create-platform-data.js

@@ -0,0 +1,103 @@
+import { parseThreadItems } from './posts-create-thread-items.js';
+import { PostsCreateValidationError } from './posts-create-validation-error.js';
+export { PostsCreateValidationError } from './posts-create-validation-error.js';
+const REPLY_SETTINGS = new Set(['following', 'mentionedUsers', 'subscribers', 'verified']);
+export function buildMediaItems(media) {
+    const urls = commaList(media);
+    if (!urls.length)
+        return undefined;
+    return urls.map((url) => ({
+        type: /\.(mp4|mov|avi|webm|m4v)$/i.test(url) ? 'video' : 'image',
+        url,
+    }));
+}
+export function buildTwitterPlatformSpecificData(options) {
+    const data = parsePlatformSpecificData(options.platformSpecificData);
+    const quoteTweetId = stringOption(options.quoteTweetId);
+    const replyToTweetId = stringOption(options.replyToTweetId);
+    const replySettings = stringOption(options.replySettings);
+    if (quoteTweetId)
+        data.quoteTweetId = quoteTweetId;
+    if (replyToTweetId)
+        data.replyToTweetId = replyToTweetId;
+    if (replySettings) {
+        if (!REPLY_SETTINGS.has(replySettings)) {
+            throw new PostsCreateValidationError('replySettings must be one of: following, mentionedUsers, subscribers, verified.', 'INVALID_REPLY_SETTINGS');
+        }
+        data.replySettings = replySettings;
+    }
+    const threadItems = parseThreadItems(options.threadJson, options.threadFile);
+    if (threadItems)
+        data.threadItems = threadItems;
+    return Object.keys(data).length ? { hasData: true, data } : { hasData: false };
+}
+export function validateTwitterPlatformSpecificData(result, platforms, mediaItems = []) {
+    if (!result.hasData || !result.data)
+        return;
+    const invalidTargets = platforms.filter((target) => !isTwitterPlatform(target.platform));
+    if (invalidTargets.length) {
+        throw new PostsCreateValidationError('X/Twitter-specific options require only twitter/x accounts.', 'TWITTER_PLATFORM_DATA_REQUIRES_TWITTER');
+    }
+    if (result.data.quoteTweetId && mediaItems.length) {
+        throw new PostsCreateValidationError('quoteTweetId cannot be combined with --media.', 'TWITTER_QUOTE_REJECTS_MEDIA');
+    }
+    if (result.data.quoteTweetId && result.data.poll) {
+        throw new PostsCreateValidationError('quoteTweetId cannot be combined with poll.', 'TWITTER_QUOTE_REJECTS_POLL');
+    }
+    if (result.data.replyToTweetId && result.data.replySettings) {
+        throw new PostsCreateValidationError('replyToTweetId cannot be combined with replySettings.', 'TWITTER_REPLY_REJECTS_REPLY_SETTINGS');
+    }
+    if (result.data.poll && mediaItems.length) {
+        throw new PostsCreateValidationError('poll cannot be combined with --media.', 'TWITTER_POLL_REJECTS_MEDIA');
+    }
+    if (result.data.threadItems && result.data.poll) {
+        throw new PostsCreateValidationError('threadItems cannot be combined with poll.', 'TWITTER_THREAD_REJECTS_POLL');
+    }
+}
+export function applyTwitterPlatformSpecificData(platforms, result) {
+    if (!result.hasData || !result.data)
+        return platforms;
+    return platforms.map((target) => ({
+        ...target,
+        platformSpecificData: {
+            ...(target.platformSpecificData || {}),
+            ...result.data,
+        },
+    }));
+}
+function parsePlatformSpecificData(input) {
+    const raw = stringOption(input);
+    if (!raw)
+        return {};
+    const parsed = parseJson(raw, '--platformSpecificData');
+    if (!isRecord(parsed) || Array.isArray(parsed)) {
+        throw new PostsCreateValidationError('--platformSpecificData must be a JSON object.', 'INVALID_PLATFORM_SPECIFIC_DATA');
+    }
+    return { ...parsed };
+}
+function parseJson(raw, optionName) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new PostsCreateValidationError(`${optionName} must contain valid JSON: ${error.message}`, 'INVALID_JSON');
+    }
+}
+function stringOption(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    return text || undefined;
+}
+function commaList(value) {
+    const raw = stringOption(value);
+    if (!raw)
+        return [];
+    return raw.split(',').map((item) => item.trim()).filter(Boolean);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isTwitterPlatform(platform) {
+    return platform === 'twitter' || platform === 'x';
+}

package/dist/utils/posts-create-thread-items.d.ts

@@ -0,0 +1 @@
+export declare function parseThreadItems(threadJson?: unknown, threadFile?: unknown): Record<string, unknown>[] | undefined;

package/dist/utils/posts-create-thread-items.js

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import { PostsCreateValidationError } from './posts-create-validation-error.js';
+export function parseThreadItems(threadJson, threadFile) {
+    const inline = stringOption(threadJson);
+    const file = stringOption(threadFile);
+    if (inline && file) {
+        throw new PostsCreateValidationError('Use either --threadJson or --threadFile, not both.', 'AMBIGUOUS_THREAD_INPUT');
+    }
+    if (inline)
+        return normalizeThreadItems(parseJson(inline, '--threadJson'));
+    if (!file)
+        return undefined;
+    const raw = readFileSync(file, 'utf8');
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('['))
+        return normalizeThreadItems(parseJson(trimmed, '--threadFile'));
+    return normalizeThreadItems(splitThreadFile(raw));
+}
+function normalizeThreadItems(input) {
+    if (!Array.isArray(input)) {
+        throw new PostsCreateValidationError('threadItems must be a JSON array.', 'INVALID_THREAD_ITEMS');
+    }
+    if (!input.length)
+        throw new PostsCreateValidationError('threadItems cannot be empty.', 'INVALID_THREAD_ITEMS');
+    return input.map((item, index) => {
+        if (typeof item === 'string') {
+            if (!item.trim()) {
+                throw new PostsCreateValidationError(`threadItems[${index}] content cannot be empty.`, 'INVALID_THREAD_ITEMS');
+            }
+            return { content: item };
+        }
+        if (!isRecord(item) || Array.isArray(item)) {
+            throw new PostsCreateValidationError(`threadItems[${index}] must be a string or object.`, 'INVALID_THREAD_ITEMS');
+        }
+        if (item.content !== undefined && typeof item.content !== 'string') {
+            throw new PostsCreateValidationError(`threadItems[${index}].content must be a string.`, 'INVALID_THREAD_ITEMS');
+        }
+        if (item.mediaItems !== undefined && !Array.isArray(item.mediaItems)) {
+            throw new PostsCreateValidationError(`threadItems[${index}].mediaItems must be an array.`, 'INVALID_THREAD_ITEMS');
+        }
+        if (!item.content && !item.mediaItems) {
+            throw new PostsCreateValidationError(`threadItems[${index}] must include content or mediaItems.`, 'INVALID_THREAD_ITEMS');
+        }
+        return { ...item };
+    });
+}
+function splitThreadFile(raw) {
+    const items = [];
+    let current = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim() === '---') {
+            pushThreadFileItem(items, current);
+            current = [];
+        }
+        else {
+            current.push(line);
+        }
+    }
+    pushThreadFileItem(items, current);
+    return items;
+}
+function pushThreadFileItem(items, lines) {
+    const content = lines.join('\n').trim();
+    if (content)
+        items.push(content);
+}
+function parseJson(raw, optionName) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new PostsCreateValidationError(`${optionName} must contain valid JSON: ${error.message}`, 'INVALID_JSON');
+    }
+}
+function stringOption(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    return text || undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/utils/posts-create-validation-error.d.ts

@@ -0,0 +1,5 @@
+export declare class PostsCreateValidationError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status?: number);
+}

package/dist/utils/posts-create-validation-error.js

@@ -0,0 +1,10 @@
+export class PostsCreateValidationError extends Error {
+    code;
+    status;
+    constructor(message, code, status = 400) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'PostsCreateValidationError';
+    }
+}

package/docs/cli.md

@@ -88,6 +88,63 @@ zernio media:upload ./photo.jpg
 
 The command implements Zernio's two-step upload: presign, direct PUT, then return public URL. Use that URL in `posts:create` or `api:call createPost`.
 
+## Posts
+
+Generic post creation:
+
+```bash
+zernio posts:create --text "Hello" --accounts <accountId>
+zernio posts:create --text "Draft" --accounts <accountId> --draft
+zernio posts:create --text "Launch" --accounts <accountId> --scheduledAt "2026-06-20T09:00:00Z"
+```
+
+Native X/Twitter fields are available on `posts:create`:
+
+```bash
+zernio posts:create \
+  --text "Thread display title" \
+  --accounts <twitterAccountId> \
+  --threadJson '["tweet 1","tweet 2"]'
+
+zernio posts:create \
+  --text "Thread display title" \
+  --accounts <twitterAccountId> \
+  --threadFile ./thread.txt
+
+zernio posts:create \
+  --text "my take" \
+  --accounts <twitterAccountId> \
+  --quoteTweetId "https://x.com/user/status/2061975910467698972"
+
+zernio posts:create \
+  --text "reply text" \
+  --accounts <twitterAccountId> \
+  --replyToTweetId "2061975910467698972"
+```
+
+`--threadJson` accepts a JSON array of strings or objects. Object items can include `mediaItems`, so per-tweet media stays inside the relevant thread item. `--threadFile` accepts either a JSON array or plain text separated by lines containing only `---`.
+
+When `threadItems` are present, top-level `--text` is only for Zernio display/search. It is not published as the root tweet; include the root tweet as `threadItems[0]`.
+
+Advanced X/Twitter passthrough:
+
+```bash
+zernio posts:create \
+  --text "custom x data" \
+  --accounts <twitterAccountId> \
+  --platformSpecificData '{"replySettings":"following"}'
+```
+
+X/Twitter-specific options reject non-X targets. `quoteTweetId` cannot be combined with top-level `--media`, and `replyToTweetId` cannot be combined with `replySettings`.
+
+For safe diagnostics on publish failures:
+
+```bash
+zernio posts:create --text "Draft" --accounts <accountId> --draft --debug-safe --pretty
+```
+
+`--debug-safe` includes resolved platform/account context and recovery hints without printing API keys or social tokens.
+
 ## Queue Scheduling
 
 Use `queuedFromProfile` and optional `queueId` in create-post payloads. Do not use `queue/next-slot` as the scheduled time; it is preview-only.

package/docs/development-roadmap.md

@@ -24,9 +24,10 @@ Status: Complete
 - Semantic-release stable/beta workflow.
 - NPM token based publish.
 
-## Phase 4 - Follow-Up
+## Phase 4 - Curated Command Follow-Up
 
-Status: Planned
+Status: In Progress
 
-- Enable GitHub Issues if `ck:vibe` issue tracking is required.
+- Enable GitHub Issues if `ck:vibe` issue tracking is required. Complete.
 - Add more curated commands for high-use endpoints discovered through real usage.
+- Add native X/Twitter `posts:create` support for quote, reply, threadItems, and safe publish diagnostics. Complete.

package/docs/project-changelog.md

@@ -14,3 +14,6 @@
 - Added coverage-gated tests for critical agent CLI paths: `api:*`, `doctor`, `platforms`, config, request construction, parsing, output, and error handling.
 - Updated docs and skill guidance for media uploads, queue scheduling, errors, rate limits, and platforms.
 - Expanded the bundled `zernio` skill to cover all shipped curated commands, full OpenAPI fallback usage, and end-to-end agent workflows.
+- Added native X/Twitter `posts:create` options for quote tweets, replies, reply settings, thread JSON/files, and advanced `platformSpecificData`.
+- Added safe `posts:create --debug-safe` diagnostics for failed publish attempts without exposing secrets.
+- Added focused tests for X platform-specific payload mapping, validation, thread parsing, and safe 401 diagnostics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zernio-cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Unofficial agent-friendly CLI for the Zernio API",
   "type": "module",
   "bin": {