@postaz/cli 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "postaz-agent",
+  "owner": {
+    "name": "Postaz",
+    "url": "https://postaz.app"
+  },
+  "metadata": {
+    "description": "Postaz TikTok scheduling skill — publish and schedule TikTok posts from an AI agent",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "postaz",
+      "description": "TikTok-first social scheduling CLI for AI agents — schedule and publish TikTok posts (video or photo slideshows), generate captions, and manage media.",
+      "source": "./",
+      "strict": false,
+      "skills": ["./"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "postaz",
+  "version": "0.1.0",
+  "description": "TikTok-first social scheduling CLI for AI agents — schedule and publish TikTok posts (video or photo slideshows), generate captions, and manage media. JSON in, JSON out.",
+  "author": {
+    "name": "Postaz",
+    "url": "https://postaz.app"
+  },
+  "homepage": "https://postaz.app",
+  "repository": "https://github.com/tonymanh-dev/postaz-agent",
+  "license": "MIT",
+  "skills": ["./"],
+  "keywords": [
+    "postaz",
+    "tiktok",
+    "social-media",
+    "scheduling",
+    "automation",
+    "ai-agent"
+  ]
+}

package/README.md

@@ -0,0 +1,81 @@
+# Postaz CLI
+
+> The cheapest way to grow your app on TikTok — from your terminal or an AI agent.
+
+`postaz` is a thin, JSON-in/JSON-out command-line wrapper over the [Postaz](https://postaz.app)
+public API. It lets you (or an AI agent) schedule and publish TikTok posts, upload media, and
+generate captions without touching the web app.
+
+## Install
+
+```bash
+npm install -g @postaz/cli
+# or
+pnpm install -g @postaz/cli
+```
+
+Requires Node.js ≥ 20.
+
+## Authenticate
+
+Create an API key in your Postaz workspace settings (**API Keys → Create key**), then:
+
+```bash
+postaz auth:login --api-key postaz_sk_xxx
+# or
+export POSTAZ_API_KEY=postaz_sk_xxx
+
+postaz auth:status
+```
+
+Credentials are stored at `~/.postaz/credentials.json` (mode `600`). The `POSTAZ_API_KEY`
+environment variable takes priority. Point at a self-hosted backend with `POSTAZ_API_URL`.
+
+## Quick start
+
+```bash
+# Find your TikTok platform id
+postaz platforms:list
+
+# Upload media (required before posting — returns a READY object with an id)
+MEDIA_ID=$(postaz upload launch.mp4 | jq -r '.id')
+
+# Publish now
+postaz posts:create -c "We just shipped 🚀 #buildinpublic" \
+  -m "$MEDIA_ID" -i "<platform-id>" --mode now
+
+# Or schedule
+postaz posts:create -c "Coming soon" -m "$MEDIA_ID" -i "<platform-id>" \
+  -s "2026-07-01T12:00:00Z"
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `auth:login --api-key <key>` | Validate and store an API key |
+| `auth:status` | Check the current key |
+| `auth:logout` | Remove stored credentials |
+| `platforms:list` | List connected accounts and their IDs |
+| `platforms:schema <id>` | Posting limits + settings for a platform |
+| `upload <file>` | Upload an image/video, returns a READY media object |
+| `media:list` | List uploaded media |
+| `media:folders:list` / `media:folders:create <name>` | Manage folders |
+| `posts:create` | Create a post (`-c` content, `-i` platform ids, `-m` media ids, `--mode`, `-s`) |
+| `posts:list` | List posts in a date range |
+| `posts:get <id>` | Fetch one post group |
+| `posts:reschedule <id> -s <iso>` | Change scheduled time |
+| `posts:delete <id>` | Delete a post |
+| `slides:content` | Generate AI captions for a slideshow (uses credits) |
+| `slides:render` | Bake captions onto images (uses credits) |
+
+Both `posts:create` and `posts create` syntaxes work. Run `postaz <command> --help` for details.
+
+## Use as an AI agent skill
+
+This repo ships a [`SKILL.md`](./SKILL.md) and a [`.claude-plugin`](./.claude-plugin) manifest so
+agents can install and drive the CLI directly. See `SKILL.md` for the full agent playbook.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: postaz
+description: Postaz is the cheapest way to grow your app on TikTok. Schedule and publish TikTok posts (one video, or a 1–35 image photo slideshow), generate captions with AI, and manage media — all from the command line or an AI agent. JSON in, JSON out.
+homepage: https://postaz.app
+metadata: {"openclaw":{"emoji":"📱","requires":{"bins":[],"env":["POSTAZ_API_KEY"]}}}
+---
+
+## Install Postaz if it doesn't exist
+
+```bash
+npm install -g @postaz/cli
+# or
+pnpm install -g @postaz/cli
+```
+
+| Property | Value |
+|----------|-------|
+| **name** | postaz |
+| **description** | TikTok-first social scheduling CLI |
+| **allowed-tools** | Bash(postaz:*) |
+
+---
+
+## ⚠️ Two Hard Rules (Read First)
+
+**Rule 1 — Authenticate before anything.** Every command needs a valid API key. Check with `postaz auth:status`.
+
+**Rule 2 — Every file you post MUST be uploaded first.** TikTok only accepts Postaz-verified HTTPS URLs, never raw local paths or external links. The workflow is always: `postaz upload <file>` → take the returned `id` → pass it to `posts:create -m`. The upload returns a `READY` object in one call (no separate finalize step).
+
+```bash
+MEDIA_ID=$(postaz upload video.mp4 | jq -r '.id')
+postaz posts:create -c "caption" -m "$MEDIA_ID" -i "<platform-id>" --mode now
+```
+
+---
+
+## Authentication
+
+Get an API key from your Postaz workspace settings (API Keys → Create key). Keys look like `postaz_sk_…` and are shown once.
+
+```bash
+# Option 1 — store it (saved to ~/.postaz/credentials.json, chmod 600)
+postaz auth:login --api-key postaz_sk_xxx
+
+# Option 2 — environment variable (takes priority over the stored file)
+export POSTAZ_API_KEY=postaz_sk_xxx
+
+# Verify
+postaz auth:status
+
+# Custom host (self-hosted backend)
+export POSTAZ_API_URL=https://api.your-domain.com
+```
+
+API access is available on **every plan, including Free**. Per-plan limits
+(posts/month, storage, connected accounts, AI credits) do the gating — a blocked
+action returns a `409` with a specific code (e.g. `post_limit_reached`).
+
+---
+
+## Core Workflow
+
+1. **Authenticate** — `postaz auth:status`
+2. **Discover** — `postaz platforms:list` to get platform IDs; `platforms:schema <id>` for limits/settings
+3. **Prepare media** — `postaz upload <file>` (required before posting)
+4. **(Optional) Generate** — `postaz slides:content` for AI captions; `slides:render` to bake captions onto images
+5. **Post** — `postaz posts:create …`
+6. **Manage** — `postaz posts:list`, `posts:get`, `posts:reschedule`, `posts:delete`
+
+```bash
+# 1. Auth
+postaz auth:status
+
+# 2. Discover
+postaz platforms:list
+PLATFORM_ID=$(postaz platforms:list | jq -r '.platforms[] | select(.provider=="tiktok") | .id' | head -n1)
+postaz platforms:schema "$PLATFORM_ID"
+
+# 3. Prepare
+MEDIA_ID=$(postaz upload promo.mp4 | jq -r '.id')
+
+# 4. Post now
+postaz posts:create -c "Try our app! #fyp" -m "$MEDIA_ID" -i "$PLATFORM_ID" --mode now
+```
+
+---
+
+## Commands
+
+Both `group:sub` (e.g. `posts:create`) and `group sub` (e.g. `posts create`) syntax work. Every command prints JSON to stdout; errors print `{ "error": { "code", "message" } }` to stderr and exit non-zero.
+
+### Authentication
+```bash
+postaz auth:login --api-key <key> [--api-url <url>]   # validate + store
+postaz auth:status                                    # check current key
+postaz auth:logout                                    # remove stored key
+```
+
+### Platforms
+```bash
+postaz platforms:list                 # connected accounts + their IDs
+postaz platforms:schema <platformId>  # content/media limits + settings fields
+```
+
+### Media
+```bash
+postaz upload <file> [--mime-type <t>] [--media-type image|video] [--folder-id <id>]
+postaz media:list [--folder-id <id|null>] [--media-type image|video]
+postaz media:folders:list
+postaz media:folders:create <name>
+```
+
+### Posts
+```bash
+# Create (date REQUIRED when --mode schedule)
+postaz posts:create -c "<content>" -i "<platformId[,platformId2]>" \
+  [-m "<mediaId[,mediaId2]>"] [--mode draft|now|schedule] \
+  [-s "2026-07-01T12:00:00Z"] [--settings '{"privacy_level":"PUBLIC_TO_EVERYONE"}']
+
+postaz posts:list [--start-date <iso>] [--end-date <iso>]
+postaz posts:get <postId>
+postaz posts:reschedule <postId> -s "2026-07-02T09:00:00Z"
+postaz posts:delete <postId>
+```
+
+`--mode` defaults to `now`, or `schedule` when `-s` is supplied. Use `draft` to
+save without queuing.
+
+### Slides (AI — consumes credits)
+```bash
+# Generate a caption + per-slide captions
+postaz slides:content -r "5 tips for launching an indie app" -n 5 \
+  [--language en] [--slide-length short|medium|long]
+
+# Bake captions onto already-uploaded images
+postaz slides:render --slides '[{"index":0,"mediaId":"<id>","caption":"Tip 1"}]' \
+  [--caption-size small|medium|large]
+```
+
+---
+
+## TikTok Posting Notes
+
+- **Media:** exactly **one video**, or **1–35 images** for a photo slideshow. Never mix video and images in one post.
+- **Settings** (pass via `--settings '{…}'`, see `platforms:schema` for the live list):
+  - `content_posting_method`: `DIRECT_POST` (publishes directly) or `UPLOAD` (sends to the TikTok inbox to finish manually).
+  - `privacy_level`: must be one the account allows — read the allowed values from `platforms:schema`.
+  - `title`, `description`, `duet`, `stitch`, `comment`, `brand_content_toggle`, `brand_organic_toggle`, `video_made_with_ai`.
+- TikTok may not return a public post ID immediately; a freshly published post can show `releaseId` as pending until processing completes.
+
+---
+
+## Common Patterns
+
+### Publish a TikTok video now
+```bash
+PLATFORM_ID=$(postaz platforms:list | jq -r '.platforms[] | select(.provider=="tiktok") | .id' | head -n1)
+MEDIA_ID=$(postaz upload launch.mp4 | jq -r '.id')
+postaz posts:create -c "We just shipped 🚀 #buildinpublic" -m "$MEDIA_ID" -i "$PLATFORM_ID" \
+  --mode now --settings '{"privacy_level":"PUBLIC_TO_EVERYONE"}'
+```
+
+### Schedule a photo slideshow
+```bash
+PLATFORM_ID=$(postaz platforms:list | jq -r '.platforms[] | select(.provider=="tiktok") | .id' | head -n1)
+M1=$(postaz upload slide1.jpg | jq -r '.id')
+M2=$(postaz upload slide2.jpg | jq -r '.id')
+M3=$(postaz upload slide3.jpg | jq -r '.id')
+postaz posts:create -c "3 reasons to try our app" -m "$M1,$M2,$M3" -i "$PLATFORM_ID" \
+  -s "2026-07-01T15:00:00Z"
+```
+
+### AI captions → render → post
+```bash
+# 1. Generate copy
+CONTENT=$(postaz slides:content -r "Why indie devs love our app" -n 4)
+# 2. Upload base images, then render captions onto them (returns composited media ids)
+#    Build the --slides array from your uploaded ids + the generated captions.
+# 3. posts:create with the rendered media ids.
+```
+
+---
+
+## Common Gotchas
+
+1. **Not authenticated** — run `postaz auth:login` or set `POSTAZ_API_KEY`.
+2. **Posting a raw file path** — you must `postaz upload` first and pass the returned `id` to `-m` (Rule 2).
+3. **`post_limit_reached` (409)** — the workspace hit its monthly post cap; upgrade the plan.
+4. **`media_not_ready`** — the media ID is wrong or not owned by this workspace. Re-upload and use the new `id`.
+5. **Wrong `privacy_level`** — use a value from `platforms:schema`; accounts differ.
+6. **Scheduling without a date** — `-s` is required when `--mode schedule`.
+7. **Mixed media** — TikTok rejects video+image in one post.
+
+---
+
+## Quick Reference
+
+```bash
+postaz auth:status                                  # check auth
+postaz platforms:list                               # get platform IDs
+postaz upload <file>                                # → { id, publicUrl, status:"READY", … }
+postaz posts:create -c "text" -m "<id>" -i "<pid>" --mode now
+postaz posts:create -c "text" -m "<id>" -i "<pid>" -s "2026-07-01T12:00:00Z"
+postaz posts:list                                   # recent posts
+postaz posts:delete <postId>
+postaz slides:content -r "topic" -n 5               # AI captions
+```

package/dist/index.js

@@ -0,0 +1,569 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/api.ts
+import { readFile as readFile2 } from "fs/promises";
+import { basename } from "path";
+
+// src/config.ts
+import { homedir } from "os";
+import { join } from "path";
+import { mkdir, readFile, writeFile, rm } from "fs/promises";
+var DEFAULT_API_URL = "https://api.postaz.app";
+var CONFIG_DIR = join(homedir(), ".postaz");
+var CREDENTIALS_PATH = join(CONFIG_DIR, "credentials.json");
+async function resolveCredentials() {
+  const envKey = process.env.POSTAZ_API_KEY?.trim();
+  if (envKey) {
+    return {
+      apiKey: envKey,
+      apiUrl: process.env.POSTAZ_API_URL?.trim() || void 0
+    };
+  }
+  const stored = await readStoredCredentials();
+  if (stored?.apiKey) {
+    return {
+      apiKey: stored.apiKey,
+      apiUrl: process.env.POSTAZ_API_URL?.trim() || stored.apiUrl
+    };
+  }
+  return null;
+}
+function resolveBaseUrl(apiUrl) {
+  const host = (apiUrl || DEFAULT_API_URL).replace(/\/+$/, "");
+  return host.endsWith("/public/v1") ? host : `${host}/public/v1`;
+}
+async function readStoredCredentials() {
+  try {
+    const raw = await readFile(CREDENTIALS_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.apiKey === "string" && parsed.apiKey) {
+      return {
+        apiKey: parsed.apiKey,
+        apiUrl: typeof parsed.apiUrl === "string" ? parsed.apiUrl : void 0
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function writeStoredCredentials(credentials) {
+  await mkdir(CONFIG_DIR, { recursive: true, mode: 448 });
+  await writeFile(
+    CREDENTIALS_PATH,
+    `${JSON.stringify(credentials, null, 2)}
+`,
+    { mode: 384 }
+  );
+  return CREDENTIALS_PATH;
+}
+async function clearStoredCredentials() {
+  try {
+    await rm(CREDENTIALS_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/output.ts
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+var CliError = class extends Error {
+  constructor(message, code = "cli_error", details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "CliError";
+  }
+  code;
+  details;
+};
+function failAndExit(error) {
+  if (error instanceof CliError) {
+    process.stderr.write(
+      `${JSON.stringify(
+        { error: { code: error.code, message: error.message, details: error.details } },
+        null,
+        2
+      )}
+`
+    );
+  } else if (error instanceof Error) {
+    process.stderr.write(
+      `${JSON.stringify(
+        { error: { code: "unexpected_error", message: error.message } },
+        null,
+        2
+      )}
+`
+    );
+  } else {
+    process.stderr.write(
+      `${JSON.stringify(
+        { error: { code: "unexpected_error", message: String(error) } },
+        null,
+        2
+      )}
+`
+    );
+  }
+  process.exit(1);
+}
+
+// src/api.ts
+var PostazApiClient = class _PostazApiClient {
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+  baseUrl;
+  apiKey;
+  /**
+   * Builds a client from an explicit key (used by `auth:login` before anything
+   * is persisted) or from resolved credentials (env → stored file).
+   */
+  static async create(options) {
+    if (options?.apiKey) {
+      return new _PostazApiClient(resolveBaseUrl(options.apiUrl), options.apiKey);
+    }
+    const credentials = await resolveCredentials();
+    if (!credentials) {
+      throw new CliError(
+        "No API key found. Run `postaz auth:login --api-key <key>` or set POSTAZ_API_KEY.",
+        "not_authenticated"
+      );
+    }
+    return new _PostazApiClient(
+      resolveBaseUrl(options?.apiUrl ?? credentials.apiUrl),
+      credentials.apiKey
+    );
+  }
+  async get(path, query) {
+    return this.request("GET", path, { query });
+  }
+  async postJson(path, body) {
+    return this.request("POST", path, { jsonBody: body });
+  }
+  async patchJson(path, body) {
+    return this.request("PATCH", path, { jsonBody: body });
+  }
+  async delete(path) {
+    await this.request("DELETE", path, {});
+  }
+  /** Uploads a local file via multipart/form-data to `POST /media`. */
+  async uploadFile(filePath, options) {
+    let bytes;
+    try {
+      bytes = await readFile2(filePath);
+    } catch {
+      throw new CliError(`File not found or unreadable: ${filePath}`, "file_unreadable");
+    }
+    const form = new FormData();
+    const fileName = basename(filePath);
+    const mimeType = options?.mimeType ?? inferMimeType(fileName);
+    form.set("file", new Blob([bytes], { type: mimeType }), fileName);
+    form.set("fileName", fileName);
+    form.set("mimeType", mimeType);
+    if (options?.mediaType) {
+      form.set("mediaType", options.mediaType);
+    }
+    if (options?.folderId !== void 0) {
+      form.set("folderId", options.folderId === null ? "null" : options.folderId);
+    }
+    return this.request("POST", "/media", { formBody: form });
+  }
+  async request(method, path, options) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (options.query) {
+      for (const [key, value] of Object.entries(options.query)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, value);
+        }
+      }
+    }
+    const headers = {
+      authorization: `Bearer ${this.apiKey}`
+    };
+    let body;
+    if (options.jsonBody !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(options.jsonBody);
+    } else if (options.formBody) {
+      body = options.formBody;
+    }
+    let response;
+    try {
+      response = await fetch(url, { method, headers, body });
+    } catch (error) {
+      throw new CliError(
+        `Could not reach the Postaz API at ${url.host}. ${error instanceof Error ? error.message : String(error)}`,
+        "network_error"
+      );
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    const text = await response.text();
+    const parsed = text ? safeJsonParse(text) : void 0;
+    if (!response.ok) {
+      const errorBody = parsed ?? {};
+      throw new CliError(
+        errorBody.message ?? `Request failed with status ${response.status}.`,
+        errorBody.code ?? `http_${response.status}`,
+        errorBody.details
+      );
+    }
+    return parsed;
+  }
+};
+function safeJsonParse(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function inferMimeType(fileName) {
+  const ext = fileName.toLowerCase().split(".").pop();
+  switch (ext) {
+    case "jpg":
+    case "jpeg":
+      return "image/jpeg";
+    case "webp":
+      return "image/webp";
+    case "mp4":
+      return "video/mp4";
+    case "webm":
+      return "video/webm";
+    case "mov":
+      return "video/quicktime";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+// src/commands/auth.ts
+function registerAuthCommands(program2) {
+  const auth = program2.command("auth").description("Authentication commands");
+  auth.command("login").description("Store a Postaz API key after validating it").requiredOption("--api-key <key>", "A postaz_sk_\u2026 API key from your workspace settings").option("--api-url <url>", "Override the API host (defaults to https://api.postaz.app)").action(async (options) => {
+    try {
+      const client = await PostazApiClient.create({
+        apiKey: options.apiKey,
+        apiUrl: options.apiUrl
+      });
+      await client.get("/platforms");
+      const path = await writeStoredCredentials({
+        apiKey: options.apiKey,
+        apiUrl: options.apiUrl
+      });
+      printJson({ status: "authenticated", credentialsPath: path });
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+  auth.command("status").description("Check whether the stored API key is valid").action(async () => {
+    try {
+      const credentials = await resolveCredentials();
+      if (!credentials) {
+        throw new CliError(
+          "Not authenticated. Run `postaz auth:login --api-key <key>` or set POSTAZ_API_KEY.",
+          "not_authenticated"
+        );
+      }
+      const client = await PostazApiClient.create();
+      const platforms = await client.get("/platforms");
+      printJson({
+        status: "authenticated",
+        source: process.env.POSTAZ_API_KEY ? "env" : "file",
+        connectedPlatforms: platforms.platforms.length
+      });
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+  auth.command("logout").description("Remove stored credentials").action(async () => {
+    try {
+      const removed = await clearStoredCredentials();
+      printJson({
+        status: removed ? "logged_out" : "no_stored_credentials",
+        credentialsPath: CREDENTIALS_PATH
+      });
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+}
+
+// src/commands/platforms.ts
+function registerPlatformCommands(program2) {
+  const platforms = program2.command("platforms").description("Discover connected social accounts (TikTok, etc.)");
+  platforms.command("list").description("List the workspace\u2019s connected platforms and their IDs").action(async () => {
+    try {
+      const client = await PostazApiClient.create();
+      printJson(await client.get("/platforms"));
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+  platforms.command("schema <platformId>").description("Get the posting schema (limits, settings fields) for a platform").action(async (platformId) => {
+    try {
+      const client = await PostazApiClient.create();
+      printJson(await client.get(`/platforms/${encodeURIComponent(platformId)}/schema`));
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+}
+
+// src/commands/media.ts
+function registerMediaCommands(program2) {
+  program2.command("upload <file>").description("Upload a local image or video and get a READY media object (with id)").option("--mime-type <type>", "Override the detected MIME type").option("--media-type <type>", "image or video (inferred from MIME type by default)").option("--folder-id <id>", "Place the upload in a media folder").action(
+    async (file, options) => {
+      try {
+        const client = await PostazApiClient.create();
+        printJson(
+          await client.uploadFile(file, {
+            mimeType: options.mimeType,
+            mediaType: options.mediaType,
+            folderId: options.folderId
+          })
+        );
+      } catch (error) {
+        failAndExit(error);
+      }
+    }
+  );
+  const media = program2.command("media").description("Media library commands");
+  media.command("list").description("List uploaded media objects").option("--folder-id <id>", 'Filter by folder id, or "null" for the root folder').option("--media-type <type>", "Filter by image or video").action(async (options) => {
+    try {
+      const client = await PostazApiClient.create();
+      printJson(
+        await client.get("/media", {
+          folderId: options.folderId,
+          mediaType: options.mediaType
+        })
+      );
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+  const folders = media.command("folders").description("Media folder commands");
+  folders.command("list").description("List media folders").action(async () => {
+    try {
+      const client = await PostazApiClient.create();
+      printJson(await client.get("/media/folders"));
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+  folders.command("create <name>").description("Create a media folder").action(async (name) => {
+    try {
+      const client = await PostazApiClient.create();
+      printJson(await client.postJson("/media/folders", { name }));
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+}
+
+// src/commands/posts.ts
+var POST_MODES = ["draft", "now", "schedule"];
+function splitIds(value) {
+  if (!value) {
+    return [];
+  }
+  return value.split(",").map((id) => id.trim()).filter(Boolean);
+}
+function registerPostCommands(program2) {
+  const posts = program2.command("posts").description("Create and manage posts");
+  posts.command("create").description("Create a post for one or more platforms").requiredOption("-c, --content <text>", "Post caption / content").requiredOption(
+    "-i, --platform <ids>",
+    "Comma-separated platform IDs (from `postaz platforms:list`)"
+  ).option(
+    "-m, --media <ids>",
+    "Comma-separated media IDs (from `postaz upload`). Required for TikTok."
+  ).option("--mode <mode>", "draft | now | schedule (default: now, or schedule if -s is set)").option("-s, --scheduled-for <iso>", "ISO 8601 time to publish, e.g. 2026-07-01T12:00:00Z").option("--settings <json>", "Provider settings as a JSON string").action(
+    async (options) => {
+      try {
+        const platformIds = splitIds(options.platform);
+        if (platformIds.length === 0) {
+          throw new CliError("At least one platform ID is required.", "platform_required");
+        }
+        const mode = resolveMode(options.mode, options.scheduledFor);
+        if (mode === "schedule" && !options.scheduledFor) {
+          throw new CliError(
+            "scheduledFor (-s) is required when --mode is schedule.",
+            "scheduled_for_required"
+          );
+        }
+        const settings = parseSettings(options.settings);
+        const mediaIds = splitIds(options.media);
+        const client = await PostazApiClient.create();
+        printJson(
+          await client.postJson("/posts", {
+            platformIds,
+            content: options.content,
+            mode,
+            ...options.scheduledFor ? { scheduledFor: options.scheduledFor } : {},
+            ...mediaIds.length > 0 ? { mediaIds } : {},
+            ...settings ? { settings } : {}
+          })
+        );
+      } catch (error) {
+        failAndExit(error);
+      }
+    }
+  );
+  posts.command("list").description("List posts in a date range (defaults to the API\u2019s default window)").option("--start-date <iso>", "ISO 8601 start of range").option("--end-date <iso>", "ISO 8601 end of range").action(async (options) => {
+    try {
+      const client = await PostazApiClient.create();
+      printJson(
+        await client.get("/posts", {
+          startDate: options.startDate,
+          endDate: options.endDate
+        })
+      );
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+  posts.command("get <postId>").description("Get a single post group (root + comments)").action(async (postId) => {
+    try {
+      const client = await PostazApiClient.create();
+      printJson(await client.get(`/posts/${encodeURIComponent(postId)}`));
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+  posts.command("reschedule <postId>").description("Change the scheduled time of a post").requiredOption("-s, --scheduled-for <iso>", "New ISO 8601 publish time").action(async (postId, options) => {
+    try {
+      const client = await PostazApiClient.create();
+      printJson(
+        await client.patchJson(`/posts/${encodeURIComponent(postId)}/schedule`, {
+          scheduledFor: options.scheduledFor
+        })
+      );
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+  posts.command("delete <postId>").description("Delete a post (and its group)").action(async (postId) => {
+    try {
+      const client = await PostazApiClient.create();
+      await client.delete(`/posts/${encodeURIComponent(postId)}`);
+      printJson({ status: "deleted", postId });
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+}
+function resolveMode(rawMode, scheduledFor) {
+  if (rawMode) {
+    if (!POST_MODES.includes(rawMode)) {
+      throw new CliError(
+        `Invalid --mode "${rawMode}". Use one of: ${POST_MODES.join(", ")}.`,
+        "invalid_mode"
+      );
+    }
+    return rawMode;
+  }
+  return scheduledFor ? "schedule" : "now";
+}
+function parseSettings(raw) {
+  if (!raw) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    throw new Error("not an object");
+  } catch {
+    throw new CliError("--settings must be a JSON object string.", "invalid_settings");
+  }
+}
+
+// src/commands/slides.ts
+function registerSlidesCommands(program2) {
+  const slides = program2.command("slides").description("AI caption generation and slideshow rendering (metered against AI credits)");
+  slides.command("content").description("Generate a caption + per-slide captions for a TikTok photo slideshow").requiredOption("-r, --request <text>", "What the slideshow should be about (max 500 chars)").requiredOption("-n, --slide-count <n>", "Number of slides (3\u201310)", (v) => Number.parseInt(v, 10)).option("-l, --language <lang>", "Language for the generated text").option(
+    "--slide-length <length>",
+    "short | medium | long \u2014 content density per slide (default: medium)"
+  ).action(
+    async (options) => {
+      try {
+        if (!Number.isInteger(options.slideCount)) {
+          throw new CliError("--slide-count must be an integer between 3 and 10.", "invalid_slide_count");
+        }
+        const client = await PostazApiClient.create();
+        printJson(
+          await client.postJson("/slides/content", {
+            userRequest: options.request,
+            slideCount: options.slideCount,
+            ...options.language ? { language: options.language } : {},
+            ...options.slideLength ? { slideLength: options.slideLength } : {}
+          })
+        );
+      } catch (error) {
+        failAndExit(error);
+      }
+    }
+  );
+  slides.command("render").description("Bake captions onto uploaded images, producing composited slide media").requiredOption(
+    "--slides <json>",
+    "JSON array of { index, mediaId, caption } objects"
+  ).option("--caption-size <size>", "small | medium | large (default: medium)").action(async (options) => {
+    try {
+      const parsed = parseSlides(options.slides);
+      const client = await PostazApiClient.create();
+      printJson(
+        await client.postJson("/slides/render", {
+          slides: parsed,
+          ...options.captionSize ? { captionSize: options.captionSize } : {}
+        })
+      );
+    } catch (error) {
+      failAndExit(error);
+    }
+  });
+}
+function parseSlides(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliError("--slides must be a valid JSON array.", "invalid_slides");
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new CliError("--slides must be a non-empty JSON array.", "invalid_slides");
+  }
+  return parsed;
+}
+
+// src/index.ts
+var program = new Command();
+program.name("postaz").description("Postaz CLI \u2014 schedule and publish TikTok posts from the terminal or an AI agent.").version("0.1.0").enablePositionalOptions();
+registerAuthCommands(program);
+registerPlatformCommands(program);
+registerMediaCommands(program);
+registerPostCommands(program);
+registerSlidesCommands(program);
+async function main() {
+  await program.parseAsync(normalizeColonArgs(process.argv));
+}
+function normalizeColonArgs(argv) {
+  const [node, script, first, ...rest] = argv;
+  if (first && /^[a-z]+:[a-z-]+$/.test(first)) {
+    const [group, sub] = first.split(":");
+    return [node, script, group, sub, ...rest];
+  }
+  return argv;
+}
+main().catch(failAndExit);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@postaz/cli",
+  "version": "0.1.0",
+  "description": "Postaz CLI — the cheapest way to grow your app on TikTok. Schedule and publish TikTok posts (video + photo slideshows), generate captions, and manage media from the command line or an AI agent.",
+  "keywords": [
+    "postaz",
+    "tiktok",
+    "social-media",
+    "scheduling",
+    "automation",
+    "ai-agent",
+    "cli"
+  ],
+  "homepage": "https://postaz.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonymanh-dev/postaz-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tonymanh-dev/postaz-agent/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "postaz": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    ".claude-plugin"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  }
+}