@palmyr/cli 1.9.0 → 1.10.0

package/dist/cli.js

@@ -778,12 +778,14 @@ const TWITTER_HELP = {
     ],
     buy: [
         { flag: '(no args)', desc: 'Purchase the oldest ready X account from the supplier pool. Default for every filter below is random.' },
-        { flag: '--country <CC>', desc: 'Filter to a specific country (ISO alpha-2: US, GB, DE, …). Run `pool-prices` first to see what is priced.' },
-        { flag: '--source web|mobile', desc: 'Filter by registration source from X about-profile. Multiplies country price by source multiplier (default 1.0).' },
-        { flag: '--max-renames N', desc: 'Cap username-change count. --max-renames 0 = never renamed. NULL on row means unknown → does not match.' },
+        { flag: '--country <CC>', desc: 'Filter by RESIDENCY (X about_profile.account_based_in). ISO alpha-2 — US, GB, DE, …. Run `pool-prices` to see what is priced.' },
+        { flag: '--registered-country <CC>', desc: 'Filter by REGISTRATION country — where the X account was created from (parsed from X "Connected via" string). May differ from --country.' },
+        { flag: '--platform android|ios|web', desc: 'Filter by registration platform (also parsed from X "Connected via" string).' },
+        { flag: '--max-renames N', desc: 'Cap username-change count. --max-renames 0 = never renamed. Rows with unknown rename count do not match.' },
+        { flag: '--source "raw string"', desc: 'Power-user: exact-match against the lowercased raw "Connected via" string. Used for fine-grained source_multiplier pricing.' },
         { flag: '--age 1y|2y|...', desc: 'Optional age category filter' },
         { flag: '(price)', desc: '$5 USDC default; country_price * source_multiplier when filters are passed.' },
-        { flag: '(example)', desc: 'palmyr twitter buy --country US --source web --max-renames 0' },
+        { flag: '(example)', desc: 'palmyr twitter buy --country GB --registered-country GB --platform android --max-renames 0' },
     ],
     login: [
         { flag: '<username>', desc: 'Force a fresh server-side session (browser runtime)' },
@@ -1012,10 +1014,23 @@ const TIKTOK_HELP = {
         { flag: '<username>', desc: 'TikTok handle to import' },
         { flag: '--sessionid <s> --csrf <c> --webid <w>', desc: 'Cookies from a logged-in TikTok browser' },
         { flag: '--credentials-line "..."', desc: 'Marketplace login:pw:email:email_pw format' },
+        { flag: '--tag <name>', desc: 'Assign a folder-like grouping tag at import' },
         { flag: '(price)', desc: 'Free — local vault only' },
     ],
+    connect: [
+        { flag: '<username>', desc: 'Log in once via your real browser; auto-captures the session' },
+        { flag: '--qr', desc: 'QR login: opens a window with a login QR for a human to scan with the TikTok app (no password/captcha)' },
+        { flag: '--country <iso-2>', desc: 'Optional — auto-detected from your browser; override e.g. --country de' },
+        { flag: '--timeout <sec>', desc: 'How long to wait for login (default 300)' },
+        { flag: '--browser-path <path>', desc: 'Override Chrome/Edge/Brave auto-detection' },
+        { flag: '--no-sandbox', desc: 'Launch without the browser sandbox (auto on root Linux; for headless/CI)' },
+        { flag: '--force', desc: 'Re-capture even if a fresh session is already cached' },
+        { flag: '--tag <name>', desc: 'Save under a folder-like grouping tag (organize many accounts)' },
+        { flag: '(price)', desc: 'Free — local, no server call' },
+    ],
     list: [
         { flag: '(no args)', desc: 'List all local TikTok accounts' },
+        { flag: '--tag <name>', desc: 'Filter to accounts in this folder/tag' },
         { flag: '(price)', desc: 'Free' },
     ],
     info: [{ flag: '<username>', desc: 'Show one account' }, { flag: '(price)', desc: 'Free' }],
@@ -1024,6 +1039,12 @@ const TIKTOK_HELP = {
         { flag: '--to <new>', desc: 'New handle' },
         { flag: '(price)', desc: 'Free — local-only metadata update' },
     ],
+    tag: [
+        { flag: '<username>', desc: 'Account to tag' },
+        { flag: '<tag-name>', desc: 'Folder name (positional) to assign' },
+        { flag: '--clear', desc: "Remove the account's tag instead" },
+        { flag: '(price)', desc: 'Free — local-only metadata' },
+    ],
     remove: [
         { flag: '<username>', desc: 'Account to delete from local vault' },
         { flag: '--confirm', desc: 'Required' },
@@ -1032,14 +1053,22 @@ const TIKTOK_HELP = {
     totp: [{ flag: '<username>', desc: 'Print current TOTP code' }, { flag: '(price)', desc: 'Free' }],
     login: [
         { flag: '<username>', desc: 'Validate cookies and cache the session' },
-        { flag: '(price)', desc: '$0.005 USDC' },
+        { flag: '(price)', desc: '$0.02 USDC' },
     ],
     session: [{ flag: '<username>', desc: 'Check cached session' }, { flag: '(price)', desc: 'Free' }],
     post: [
         { flag: '<username>', desc: 'Account to post from' },
         { flag: '--file video.mp4', desc: 'Video file' },
         { flag: '--caption "..."', desc: 'Caption' },
-        { flag: '(price)', desc: '$0.001 USDC' },
+        { flag: '--privacy 0|1|2', desc: 'Audience: 0 public (default) · 1 friends · 2 private' },
+        { flag: '(price)', desc: '$0.01 USDC' },
+    ],
+    schedule: [
+        { flag: '<username>', desc: 'Account to post from' },
+        { flag: '--at <iso8601>', desc: 'When TikTok publishes it — ~15 min to ~10 days out' },
+        { flag: '--file video.mp4 | --url <https>', desc: 'Video' },
+        { flag: '--caption "..."', desc: 'Caption' },
+        { flag: '(price)', desc: "Same as post — uses TikTok's own scheduler" },
     ],
     follow: [
         { flag: '<username>', desc: 'Account doing the follow' },
@@ -1071,6 +1100,47 @@ const TIKTOK_HELP = {
         { flag: '--file pic.png', desc: 'Image file' },
         { flag: '(price)', desc: '$0.005 USDC' },
     ],
+    draft: [
+        { flag: '<username>', desc: 'Account to post from' },
+        { flag: '--file video.mp4 | --url <https>', desc: 'Video' },
+        { flag: '--caption "..."', desc: 'Caption' },
+        { flag: '--privacy 0|1|2', desc: 'Audience: 0 public (default) · 1 friends · 2 private' },
+        { flag: '--at <iso8601>', desc: 'Optional — schedule on approval instead of posting now' },
+        { flag: '(price)', desc: 'Free — queues for approval; you pay on approve' },
+    ],
+    drafts: [
+        { flag: '[<username>]', desc: 'List drafts awaiting approval (optionally for one account)' },
+        { flag: '--tag <name>', desc: 'Filter by folder/tag' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    approve: [
+        { flag: '<draft-id>', desc: 'Publish the queued draft + write it to the post log' },
+        { flag: '(price)', desc: "Same as post — $0.01 (a scheduled draft uses TikTok's scheduler)" },
+    ],
+    reject: [
+        { flag: '<draft-id>', desc: 'Discard a queued draft' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    logs: [
+        { flag: '[<username>]', desc: 'Recent posts (audit log) — approved drafts + direct posts' },
+        { flag: '--tag <name>', desc: 'Filter by folder/tag' },
+        { flag: '--limit <N>', desc: 'How many to show (default 20)' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    analytics: [
+        { flag: '<username>', desc: 'Scrape per-post views/likes/comments, categorize into tiers, snapshot the time-series' },
+        { flag: '(price)', desc: '$0.005 USDC (free in self-hosted mode)' },
+    ],
+    review: [
+        { flag: '<username>', desc: 'Performance review — best/worst, tier mix, engagement, trend vs last snapshot' },
+        { flag: '(price)', desc: 'Free — reads the local snapshot store' },
+    ],
+    monitor: [
+        { flag: 'tick | start | stop | status', desc: 'Unattended analytics loop (self-learning)' },
+        { flag: '--every <6h|30m>', desc: 'Interval for `start` (default 6h)' },
+        { flag: '--account a,b', desc: 'Limit to specific accounts (default: all connected)' },
+        { flag: '(price)', desc: 'Free locally; each tick runs `analytics`' },
+    ],
 };
 /**
  * Render a per-command menu (no subcommand given). On a TTY → Ink MenuScreen
@@ -1228,10 +1298,10 @@ async function main() {
     AGENT_MODE = !process.stdout.isTTY || !!flags.json || process.env.PALMYR_JSON === '1';
     setUiAgentMode(AGENT_MODE);
     if (flags.version) {
-        if (AGENT_MODE) {
-            // Agents need to disambiguate "CLI npm package version" from "Palmyr API
-            // server version" and the Node runtime — emit all three so they don't
-            // have to call multiple commands to assemble a support report.
+        // `--version` follows the universal CLI convention: a bare version string on
+        // stdout so wrappers/CI can grep it. Agents that want the richer cli/node/
+        // platform report opt in explicitly with --json (or PALMYR_JSON=1).
+        if (AGENT_MODE && (!!flags.json || process.env.PALMYR_JSON === '1')) {
             print({
                 cliPackageVersion: VERSION,
                 version: VERSION, // back-compat alias for the legacy {version} shape
@@ -3125,8 +3195,6 @@ async function main() {
                             err('No session secret found. Was this wallet created on this machine?');
                         const data = await ao.walletConfig(walletId, sessionSecret);
                         return print(data);
-                        print(data.config || data);
-                        break;
                     }
                     case 'use': {
                         const walletId = positional[0] || flags.id;
@@ -6274,17 +6342,27 @@ async function main() {
                         return print({ success: true, platform, username, op: subcommand, ...(data?.data || {}) });
                     }
                     case 'buy': {
-                        // Agents say "buy" with optional --country / --source / --max-renames.
-                        // Each filter is independent (default: random across that
-                        // dimension). Pricing = country_price * source_multiplier:
-                        //   - --country US               → country_prices.US (e.g. $8)
-                        //   - --source web               → multiplied by web's row in
-                        //                                  source_multipliers (e.g. 1.2)
-                        //   - --max-renames 0            → filter only, no price impact
-                        // Without --country, falls back to the legacy $5 flat rate.
+                        // Agents say "buy" with optional filters. Each is independent
+                        // (default: random across that dimension).
+                        //
+                        //   --country GB              account_based_in = United Kingdom (residency)
+                        //   --registered-country GB   X's "Connected via …" country
+                        //   --platform android|ios|web   X's "Connected via" platform
+                        //   --max-renames 0           never-renamed accounts only
+                        //   --source "raw string"     exact-match on the raw "Connected via" string (power user)
+                        //
+                        // Pricing = country_price * source_multiplier (multiplier
+                        // defaults to 1.0 when no source row exists). Without --country,
+                        // falls back to the legacy $5 flat rate.
                         const country = (flags.country || '').trim().toUpperCase() || undefined;
                         const ageCategory = flags.age || flags['age-category'] || undefined;
                         const source = (flags.source || '').trim().toLowerCase() || undefined;
+                        const registeredCountry = (flags['registered-country'] || '').trim().toUpperCase() || undefined;
+                        const platformFlag = (flags.platform || '').trim().toLowerCase() || undefined;
+                        if (platformFlag && !['android', 'ios', 'web'].includes(platformFlag)) {
+                            err('--platform must be one of: android, ios, web');
+                        }
+                        const registeredPlatform = platformFlag;
                         const maxRenamesRaw = flags['max-renames'];
                         const maxUsernameChanges = maxRenamesRaw === undefined || maxRenamesRaw === ''
                             ? undefined
@@ -6294,7 +6372,12 @@ async function main() {
                         }
                         let data;
                         try {
-                            data = await ao.socialTwitterBuy(country, ageCategory, { source, maxUsernameChanges });
+                            data = await ao.socialTwitterBuy(country, ageCategory, {
+                                source,
+                                registeredCountry,
+                                registeredPlatform,
+                                maxUsernameChanges,
+                            });
                         }
                         catch (e) {
                             err(`Buy failed: ${e.message}`, EXIT.GENERAL);
@@ -6308,6 +6391,8 @@ async function main() {
                         // pre-seasoned at pool-add time.
                         const filterTags = [
                             country && `country=${country}`,
+                            registeredCountry && `registered_country=${registeredCountry}`,
+                            registeredPlatform && `platform=${registeredPlatform}`,
                             source && `source=${source}`,
                             maxUsernameChanges !== undefined && `max_renames=${maxUsernameChanges}`,
                         ].filter(Boolean).join(', ');
@@ -6323,6 +6408,8 @@ async function main() {
                             platform,
                             username: summary.username,
                             country: account.country,
+                            registered_country: account.registered_country,
+                            registered_platform: account.registered_platform,
                             source: account.source,
                             username_change_count: account.username_change_count,
                             account_based_in: account.account_based_in,
@@ -6963,6 +7050,8 @@ async function main() {
             }
             case 'tiktok': {
                 const sv = await import('./social-vault.js');
+                const sd = await import('./social-drafts.js');
+                const sa = await import('./social-analytics.js');
                 const platform = 'tiktok';
                 // Same help guard as `twitter` — prevents `--help` from dispatching
                 // a paid subcommand. Same bug class lived here too in 1.8.3.
@@ -6971,23 +7060,34 @@ async function main() {
                         command: 'tiktok',
                         title: 'tiktok',
                         subtitle: 'Automated TikTok account management',
-                        footerLeft: 'BYO: export sessionid from a logged-in TikTok browser, import, then post / follow / like.',
+                        footerLeft: 'Start with `connect`: log in once in your own browser, then post / follow / like — all server-side.',
                         commands: [
-                            { name: 'import', description: 'Save a BYO TikTok account. Pass --credentials-line "login:pw:email:email_pw" from a marketplace, or extract cookies from DevTools → Application → Cookies → .tiktok.com and pass --sessionid.', hint: '--credentials-line "..." OR <username> --sessionid ... --csrf ... --webid ...' },
-                            { name: 'list', description: 'List all local TikTok accounts' },
+                            { name: 'connect', description: 'Log in once via your own browser — opens TikTok, you sign in (incl. captcha/2FA), and Palmyr auto-captures the session into the local vault. Auto-creates the account and infers the country from your browser. This is the easy path.', hint: '<username> [--tag <folder>]' },
+                            { name: 'import', description: 'Manual fallback to `connect`: save a BYO account from a marketplace --credentials-line "login:pw:email:email_pw", or paste cookies from DevTools → Application → Cookies → .tiktok.com via --sessionid.', hint: '--credentials-line "..." OR <username> --sessionid ... --csrf ... --webid ...' },
+                            { name: 'list', description: 'List local TikTok accounts; --tag filters to one folder', hint: '[--tag <folder>]' },
                             { name: 'info', description: 'Show one account', hint: '<username>' },
                             { name: 'rename', description: 'Update the local handle', hint: '<old> --to <new>' },
+                            { name: 'tag', description: 'Group an account under a folder-like tag so one agent can organize 30+ accounts; --clear removes it', hint: '<username> <folder> | <username> --clear' },
                             { name: 'remove', description: 'Delete an account from the local vault', hint: '<username> --confirm' },
                             { name: 'totp', description: 'Print the current TOTP code', hint: '<username>' },
                             { name: 'login', description: 'Validate cookies and cache the session', hint: '<username>' },
                             { name: 'session', description: 'Check cached session status', hint: '<username>' },
                             { name: 'post', description: 'Post a video', hint: '<username> --file video.mp4 --caption "..."' },
+                            { name: 'schedule', description: "Schedule a video via TikTok's own scheduler (~15 min to ~10 days out) — fires even if your machine and our server are off.", hint: '<username> --at 2026-06-03T18:00Z --file v.mp4 --caption "..."' },
                             { name: 'follow', description: 'Follow a TikTok user', hint: '<username> --user @handle' },
                             { name: 'like', description: 'Like a video', hint: '<username> --video https://...' },
                             { name: 'delete', description: 'Delete a video', hint: '<username> --video https://...' },
                             { name: 'bio', description: 'Update bio (<=80 chars)', hint: '<username> --text "..."' },
                             { name: 'name', description: 'Update display name (<=30 chars)', hint: '<username> --display "..."' },
                             { name: 'pfp', description: 'Update avatar', hint: '<username> --file pic.png' },
+                            { name: 'draft', description: 'Stage a post for human approval instead of publishing — queues it locally (free).', hint: '<username> --file v.mp4 --caption "..." [--at <iso>]' },
+                            { name: 'drafts', description: 'List drafts awaiting approval', hint: '[<username>] [--tag <folder>]' },
+                            { name: 'approve', description: 'Publish a queued draft + record it in the post log', hint: '<draft-id>' },
+                            { name: 'reject', description: 'Discard a queued draft', hint: '<draft-id>' },
+                            { name: 'logs', description: 'Audit log of posts that went out (approved drafts + direct posts)', hint: '[<username>] [--tag <folder>] [--limit N]' },
+                            { name: 'analytics', description: 'Scrape per-post views/likes/comments, categorize into tiers vs the account’s own posts, and snapshot the time-series', hint: '<username>' },
+                            { name: 'review', description: 'Performance review: best/worst posts, tier mix, engagement, and trend vs the last snapshot — the self-learning surface', hint: '<username>' },
+                            { name: 'monitor', description: 'Unattended loop that periodically runs analytics so review stays fresh (mirrors the wallet daemon)', hint: 'tick | start --every 6h | stop | status' },
                         ],
                         fromHome,
                     });
@@ -7087,14 +7187,16 @@ async function main() {
                         const summary = sv.importAccount(platform, username, creds, {
                             source: line ? 'marketplace-line' : 'import',
                             country,
+                            tag: flags.tag,
                         });
                         const loginPath = sessionid ? 'cookie-injection' : 'form-login (requires CAPSOLVER_API_KEY server-side)';
                         log(`tiktok import: ${summary.username} (${summary.id}) [login: ${loginPath}, country: ${country}]`);
                         return print({ ...summary, has_sessionid: !!sessionid, has_password: !!password, login_path: loginPath });
                     }
                     case 'list': {
-                        const accounts = sv.listAccounts(platform);
-                        return print({ accounts, count: accounts.length });
+                        const tagFilter = flags.tag;
+                        const accounts = sv.listAccounts(platform, tagFilter);
+                        return print({ accounts, count: accounts.length, ...(tagFilter ? { tag: tagFilter } : {}) });
                     }
                     case 'info': {
                         const username = positional[0] || flags.username;
@@ -7116,6 +7218,19 @@ async function main() {
                         log(`tiktok rename: ${oldUsername} → ${newUsername}`);
                         return print(summary);
                     }
+                    case 'tag': {
+                        // Folder-like grouping so one agent can organize 30+ accounts.
+                        const username = positional[0] || flags.username;
+                        if (!username)
+                            err('<username> required');
+                        const clear = !!flags.clear;
+                        const newTag = clear ? null : (positional[1] || flags.tag);
+                        if (!clear && !newTag)
+                            err('provide a tag (e.g. `palmyr tiktok tag <username> brand-x`) or --clear');
+                        const summary = sv.tagAccount(platform, username, newTag);
+                        log(clear ? `tiktok tag: cleared on ${username}` : `tiktok tag: ${username} → ${newTag}`);
+                        return print(summary);
+                    }
                     case 'remove': {
                         const username = positional[0] || flags.username;
                         if (!username)
@@ -7144,6 +7259,113 @@ async function main() {
                             expires_in_seconds: secondsUntilNextCode(),
                         });
                     }
+                    case 'connect': {
+                        // Real-browser login. Launches the operator's own Chrome/Edge,
+                        // they sign in (solving any captcha/2FA themselves), and we harvest
+                        // the session via CDP — no headless form-driving, no captcha solver.
+                        // Agent-smooth: auto-provisions the account, auto-detects login
+                        // (no keystroke), and always terminates with structured JSON.
+                        const username = positional[0] || flags.username;
+                        if (!username)
+                            err('<username> required');
+                        // --country is optional: if omitted we infer it from the real
+                        // browser during login (locale/timezone). Explicit flag overrides.
+                        const explicitCountry = flags.country?.toLowerCase();
+                        let acc = sv.getAccount(platform, username);
+                        // Idempotent: an existing account with a fresh cached session returns
+                        // fast, no browser. (New accounts have no session yet.) Lets an agent
+                        // call `connect` defensively before a run.
+                        if (acc && !flags.force) {
+                            const existing = sv.loadSession(acc.id);
+                            if (existing && existing.cookies?.length) {
+                                const ageH = sv.sessionAgeHours(acc.id) ?? 999;
+                                if (ageH < 12) {
+                                    return print({
+                                        success: true, platform, username, connected: true, already: true,
+                                        cookies: existing.cookies.length,
+                                        age_hours: Number(ageH.toFixed(2)),
+                                        captured_at: existing.captured_at,
+                                        hint: 'Session is fresh. Pass --force to re-capture.',
+                                    });
+                                }
+                            }
+                        }
+                        const { connectTikTok } = await import('./tiktok-connect.js');
+                        const timeoutSec = flags.timeout !== undefined ? Math.max(30, Number(flags.timeout)) : 300;
+                        let hostedLink;
+                        const result = await connectTikTok({
+                            country: explicitCountry || acc?.country,
+                            timeoutMs: timeoutSec * 1000,
+                            browserPath: flags['browser-path'],
+                            noSandbox: !!flags['no-sandbox'],
+                            qr: !!flags.qr,
+                            onQr: async (dataUrl) => {
+                                // Host the QR so the agent gets a clean link to forward. Best-effort:
+                                // if the server lacks the endpoint, the PNG/data-URL still work.
+                                try {
+                                    const hosted = await ao.socialTiktokHostQr(dataUrl);
+                                    hostedLink = `${ao.api.replace(/\/+$/, '')}/connect/${hosted.token}`;
+                                    process.stderr.write(`[connect] QR link (send to a human): ${hostedLink}\n`);
+                                }
+                                catch { /* hosting optional */ }
+                            },
+                            onProgress: (m) => process.stderr.write(`[connect] ${m}\n`),
+                        });
+                        if (!result.success) {
+                            const details = { platform, username, reason: result.reason };
+                            if (result.qrPngPath)
+                                details.qr_png_path = result.qrPngPath;
+                            if (hostedLink)
+                                details.qr_link = hostedLink;
+                            if (result.reason === 'no_local_browser') {
+                                details.remedy =
+                                    `No Chrome/Edge/Brave found. Install one, pass --browser-path <path>, or import cookies manually: ` +
+                                        `open tiktok.com (logged in) → DevTools → Application → Cookies → .tiktok.com, then ` +
+                                        `palmyr tiktok import ${username} --country us --sessionid <sessionid> --csrf <tt_csrf_token> --webid <tt_webid_v2>`;
+                            }
+                            err(`connect failed: ${result.error || result.reason}`, EXIT.GENERAL, details);
+                        }
+                        // Country precedence: existing account keeps its stored value;
+                        // otherwise explicit flag > detected-from-browser > env default > us.
+                        // Agents never have to know or pass it.
+                        const resolvedCountry = acc?.country ||
+                            explicitCountry ||
+                            result.detectedCountry ||
+                            process.env.PALMYR_DEFAULT_COUNTRY?.toLowerCase() ||
+                            'us';
+                        const countrySource = acc?.country
+                            ? 'account'
+                            : explicitCountry
+                                ? 'flag'
+                                : result.detectedCountry
+                                    ? 'detected'
+                                    : 'default';
+                        // Auto-create the account now that the country is known (one command,
+                        // not import-then-connect).
+                        if (!acc) {
+                            acc = sv.importAccount(platform, username, { login: username, password: 'unknown' }, { source: 'connect', country: resolvedCountry, tag: flags.tag });
+                            process.stderr.write(`[connect] created local account ${username} (${acc.id}) [country: ${resolvedCountry}, ${countrySource}]\n`);
+                        }
+                        else if (flags.tag) {
+                            // Re-connecting an existing account with --tag (re)assigns the folder.
+                            sv.tagAccount(platform, username, flags.tag);
+                        }
+                        // Persist into the same encrypted session cache that post/follow/like read.
+                        sv.saveSession(acc.id, platform, result.cookies || []);
+                        sv.updateMeta(platform, username, { last_action_at: new Date().toISOString() });
+                        return print({
+                            success: true, platform, username, connected: true,
+                            browser: result.browser,
+                            country: resolvedCountry,
+                            country_source: countrySource,
+                            cookies_captured: result.cookiesCaptured,
+                            sessionid_present: true,
+                            ...(flags.tag ? { tag: flags.tag } : {}),
+                            ...(result.qrPngPath ? { qr_png_path: result.qrPngPath } : {}),
+                            ...(hostedLink ? { qr_link: hostedLink } : {}),
+                            next: `palmyr tiktok post ${username} --file video.mp4 --caption "..."`,
+                        });
+                    }
                     case 'login': {
                         const username = positional[0] || flags.username;
                         if (!username)
@@ -7220,7 +7442,202 @@ async function main() {
                             stale: (ageHours || 0) > 12,
                         });
                     }
+                    case 'draft': {
+                        // Stage a post for human approval — does NOT publish. Free, local.
+                        const username = positional[0] || flags.username;
+                        if (!username)
+                            err('<username> required');
+                        const acc = sv.getAccount(platform, username);
+                        if (!acc)
+                            err(`tiktok account "${username}" not found locally`, EXIT.NOT_FOUND);
+                        const caption = flags.caption || flags.body || flags.text;
+                        if (!caption)
+                            err('--caption "..." required');
+                        const filePath = flags.file || flags.path;
+                        const videoUrl = flags.url;
+                        if (!filePath && !videoUrl)
+                            err('--file <local-path> or --url <https-url> required');
+                        if (filePath) {
+                            const { existsSync, statSync } = await import('fs');
+                            if (!existsSync(filePath))
+                                err(`File not found: ${filePath}`, EXIT.NOT_FOUND);
+                            if (statSync(filePath).size > 100 * 1024 * 1024)
+                                err('Video too large (max 100 MB)', EXIT.BAD_INPUT);
+                        }
+                        const privacy = flags.privacy !== undefined ? Number(flags.privacy) : undefined;
+                        let schedule_at;
+                        const at = flags.at || flags.when;
+                        if (at) {
+                            const when = new Date(at);
+                            if (isNaN(when.getTime()))
+                                err('--at must be a valid ISO-8601 datetime', EXIT.BAD_INPUT);
+                            const ms = when.getTime() - Date.now();
+                            if (ms < 15 * 60 * 1000)
+                                err('--at must be at least ~15 minutes in the future', EXIT.BAD_INPUT);
+                            if (ms > 10 * 24 * 60 * 60 * 1000)
+                                err('--at must be within ~10 days', EXIT.BAD_INPUT);
+                            schedule_at = when.toISOString();
+                        }
+                        const absFile = filePath ? (await import('path')).resolve(filePath) : undefined;
+                        const draft = sd.createDraft({
+                            platform, account: username, caption, file: absFile, url: videoUrl,
+                            privacy, tag: flags.tag || acc.tag, schedule_at,
+                        });
+                        log(`tiktok draft ${draft.id} staged for ${username} (awaiting approval)`);
+                        return print({
+                            draft_id: draft.id, status: draft.status, account: username, caption,
+                            ...(draft.tag ? { tag: draft.tag } : {}), ...(schedule_at ? { schedule_at } : {}),
+                            next: `palmyr tiktok approve ${draft.id}`,
+                        });
+                    }
+                    case 'drafts': {
+                        const drafts = sd.listDrafts({ platform, account: positional[0] || flags.account, tag: flags.tag });
+                        return print({
+                            drafts: drafts.map(d => ({ id: d.id, account: d.account, caption: d.caption, privacy: d.privacy, tag: d.tag, schedule_at: d.schedule_at, created_at: d.created_at })),
+                            count: drafts.length,
+                        });
+                    }
+                    case 'reject': {
+                        const id = positional[0] || flags.id;
+                        if (!id)
+                            err('<draft-id> required');
+                        if (!sd.deleteDraft(id))
+                            err(`draft "${id}" not found`, EXIT.NOT_FOUND);
+                        log(`tiktok reject ${id}`);
+                        return print({ rejected: true, draft_id: id });
+                    }
+                    case 'logs': {
+                        const entries = sd.readPostLog({
+                            platform, account: positional[0] || flags.account,
+                            tag: flags.tag, limit: flags.limit ? Number(flags.limit) : 20,
+                        });
+                        return print({ posts: entries, count: entries.length });
+                    }
+                    case 'approve': {
+                        // Publish a queued draft from the human-in-the-loop flow + log it.
+                        const id = positional[0] || flags.id;
+                        if (!id)
+                            err('<draft-id> required');
+                        const draft = sd.getDraft(id);
+                        if (!draft)
+                            err(`draft "${id}" not found`, EXIT.NOT_FOUND);
+                        const acc = sv.getAccount(platform, draft.account);
+                        if (!acc)
+                            err(`account "${draft.account}" for draft ${id} not found locally`, EXIT.NOT_FOUND);
+                        const sess = sv.loadSession(acc.id);
+                        if (!sess || !sess.cookies || sess.cookies.length === 0) {
+                            err(`No cached session for ${draft.account}. Run 'tiktok connect ${draft.account}' first.`, EXIT.NOT_FOUND);
+                        }
+                        const psid = sv.getProxySessionId(platform, draft.account);
+                        const country = sv.getCountry(platform, draft.account);
+                        const media = {};
+                        if (draft.file) {
+                            const { readFileSync, existsSync, statSync } = await import('fs');
+                            if (!existsSync(draft.file))
+                                err(`Draft video no longer exists at ${draft.file}`, EXIT.NOT_FOUND);
+                            if (statSync(draft.file).size > 100 * 1024 * 1024)
+                                err('Video too large (max 100 MB)', EXIT.BAD_INPUT);
+                            media.video_base64 = `data:video/mp4;base64,${readFileSync(draft.file).toString('base64')}`;
+                        }
+                        else {
+                            media.video_url = draft.url;
+                        }
+                        let data;
+                        try {
+                            data = await ao.socialTiktokPost(acc.id, sess.cookies, draft.caption, media, { privacy: draft.privacy, schedule_at: draft.schedule_at }, psid, country);
+                        }
+                        catch (e) {
+                            err(`approve failed: ${e.message}`, EXIT.GENERAL);
+                        }
+                        if (!data?.success) {
+                            // Keep the draft so it can be retried (e.g. after re-connecting a stale session).
+                            err(`approve failed: ${data?.error || 'unknown'}${data?.error_code ? ` [${data.error_code}]` : ''}`, EXIT.GENERAL);
+                        }
+                        sv.updateMeta(platform, draft.account, { last_action_at: new Date().toISOString() });
+                        const entry = sd.appendPostLog({ platform, account: draft.account, caption: draft.caption, source: 'draft', status: draft.schedule_at ? 'scheduled' : 'posted', url: data?.data?.video_url, tag: draft.tag, draft_id: id, result: data?.data });
+                        sd.deleteDraft(id);
+                        log(`tiktok approve ${id} → ${entry.status} for ${draft.account}`);
+                        return print({ approved: true, draft_id: id, account: draft.account, status: entry.status, ...(data?.data || {}) });
+                    }
+                    case 'analytics': {
+                        const username = positional[0] || flags.username;
+                        if (!username)
+                            err('<username> required');
+                        const acc = sv.getAccount(platform, username);
+                        if (!acc)
+                            err(`tiktok account "${username}" not found locally`, EXIT.NOT_FOUND);
+                        const sess = sv.loadSession(acc.id);
+                        if (!sess || !sess.cookies || sess.cookies.length === 0) {
+                            err(`No cached session for ${username}. Run 'tiktok connect ${username}' first.`, EXIT.NOT_FOUND);
+                        }
+                        const psid = sv.getProxySessionId(platform, username);
+                        const country = sv.getCountry(platform, username);
+                        let data;
+                        try {
+                            data = await ao.socialTiktokAnalytics(acc.id, sess.cookies, psid, country);
+                        }
+                        catch (e) {
+                            err(`analytics failed: ${e.message}`, EXIT.GENERAL);
+                        }
+                        if (!data?.success) {
+                            err(`analytics failed: ${data?.error || 'unknown'}${data?.error_code ? ` [${data.error_code}]` : ''}`, EXIT.GENERAL);
+                        }
+                        // Categorize (relative tiers) + snapshot to the local time-series so
+                        // `review` can show trends. `tiktok monitor` calls this same op.
+                        const snap = sa.appendSnapshot(username, data?.data?.posts || []);
+                        return print({ platform, username, scraped_at: data?.data?.scraped_at, summary: snap.summary, posts: snap.posts });
+                    }
+                    case 'review': {
+                        const username = positional[0] || flags.username;
+                        if (!username)
+                            err('<username> required');
+                        return print(sa.review(username));
+                    }
+                    case 'monitor': {
+                        // Unattended self-learning loop: periodically run `analytics` (scrape
+                        // + categorize + snapshot) for the monitored accounts. Mirrors the
+                        // wallet daemon — tick / start / stop / status.
+                        const sm = await import('./social-monitor.js');
+                        const sub = positional[0] || 'status';
+                        const cliPath = process.argv[1];
+                        const resolveAccounts = () => {
+                            const flagAcc = flags.account;
+                            if (flagAcc)
+                                return flagAcc.split(',').map((s) => s.trim()).filter(Boolean);
+                            return sv.listAccounts(platform).map((a) => a.username);
+                        };
+                        if (sub === 'tick') {
+                            const accounts = resolveAccounts();
+                            if (!accounts.length)
+                                err('No TikTok accounts to monitor — connect one first.', EXIT.NOT_FOUND);
+                            return print({ ticked: accounts.length, results: sm.monitorTick(cliPath, accounts) });
+                        }
+                        if (sub === 'start') {
+                            const accounts = resolveAccounts();
+                            if (!accounts.length)
+                                err('No TikTok accounts to monitor — connect one first.', EXIT.NOT_FOUND);
+                            const intervalSeconds = sm.parseInterval(flags.every || flags.interval, 21600);
+                            const { pid } = sm.startMonitor(cliPath, { intervalSeconds, accounts });
+                            return print({ started: true, pid, every_seconds: intervalSeconds, accounts });
+                        }
+                        if (sub === 'stop') {
+                            const r = await sm.stopMonitor();
+                            return print({ stopped: r.wasRunning, pid: r.pid });
+                        }
+                        if (sub === 'status') {
+                            return print(sm.monitorStatus());
+                        }
+                        if (sub === '_run') {
+                            const intervalSeconds = sm.parseInterval(flags.interval, 21600);
+                            const accounts = resolveAccounts();
+                            await sm.runMonitorLoop(cliPath, { intervalSeconds, accounts });
+                            return;
+                        }
+                        err(`Unknown monitor action: ${sub}. Try: tick, start, stop, status`, EXIT.BAD_INPUT);
+                        return;
+                    }
                     case 'post':
+                    case 'schedule':
                     case 'follow':
                     case 'like':
                     case 'delete':
@@ -7241,7 +7658,7 @@ async function main() {
                         const country = sv.getCountry(platform, username);
                         let data;
                         try {
-                            if (subcommand === 'post') {
+                            if (subcommand === 'post' || subcommand === 'schedule') {
                                 const caption = flags.caption || flags.body || flags.text;
                                 if (!caption)
                                     err('--caption "..." required');
@@ -7264,7 +7681,28 @@ async function main() {
                                     media.video_url = videoUrl;
                                 }
                                 const privacy = flags.privacy !== undefined ? Number(flags.privacy) : undefined;
-                                data = await ao.socialTiktokPost(acc.id, sess.cookies, caption, media, { privacy }, psid, country);
+                                // `schedule` is `post` with a future time — drives TikTok's own
+                                // scheduler. Validate the window client-side for fast feedback;
+                                // the server re-checks and renders it into the account timezone.
+                                let schedule_at;
+                                if (subcommand === 'schedule') {
+                                    const at = flags.at || flags.when;
+                                    if (!at)
+                                        err('--at <iso8601> required (e.g. --at 2026-06-03T18:00:00Z)');
+                                    const when = new Date(at);
+                                    if (isNaN(when.getTime()))
+                                        err('--at must be a valid ISO-8601 datetime (e.g. 2026-06-03T18:00:00Z)', EXIT.BAD_INPUT);
+                                    const ms = when.getTime() - Date.now();
+                                    if (ms < 15 * 60 * 1000)
+                                        err('--at must be at least ~15 minutes in the future (TikTok minimum)', EXIT.BAD_INPUT);
+                                    if (ms > 10 * 24 * 60 * 60 * 1000)
+                                        err('--at must be within ~10 days (TikTok maximum)', EXIT.BAD_INPUT);
+                                    schedule_at = when.toISOString();
+                                }
+                                data = await ao.socialTiktokPost(acc.id, sess.cookies, caption, media, { privacy, schedule_at }, psid, country);
+                                if (data?.success) {
+                                    sd.appendPostLog({ platform, account: username, caption, source: 'direct', status: schedule_at ? 'scheduled' : 'posted', url: data?.data?.video_url, tag: acc.tag, result: data?.data });
+                                }
                             }
                             else if (subcommand === 'follow') {
                                 const target = flags.user || flags.target;
@@ -7328,7 +7766,7 @@ async function main() {
                         return print({ success: true, platform, username, op: subcommand, ...(data?.data || {}) });
                     }
                     default:
-                        err(`Unknown tiktok command: ${subcommand}. Try: import, list, info, rename, remove, totp, login, session, post, follow, like, delete, bio, name, pfp`);
+                        err(`Unknown tiktok command: ${subcommand}. Try: connect, import, list, info, rename, tag, remove, totp, login, session, post, schedule, draft, drafts, approve, reject, logs, analytics, review, monitor, follow, like, delete, bio, name, pfp`);
                 }
                 break;
             }