Use with AI agents

The CLI is designed to be driven by an AI agent as much as by a human. It reads flags and emits a single JSON document on stdout, so an agent can connect a content workflow to TikTok without ever touching the web app.

Why it suits agents

• JSON in, JSON out. Every command prints one JSON document to stdout — easy to parse, no scraping.
• Stable error codes. Failures print { "error": { "code", "message" } } to stderr and exit 1. Branch on code, never on prose.
• Stateless auth. Set LOOMTA_API_KEY in the environment and every command is authenticated — no interactive login step.

Setup for an agent

1. Install the CLI:

   npm install -g @loomta/cli

2. Provide a key via the environment (wins over any saved file):

   export LOOMTA_API_KEY=loomta_sk_xxx

3. Confirm it resolves before doing anything else:

   loomta auth:status   # { "status": "authenticated", "connectedPlatforms": N }

The bundled skill (Claude Code)

The CLI ships an agent skill so it can be installed as a tool/plugin:

• SKILL.md — an agent playbook: install, auth, the command set, what TikTok expects, worked examples, and a failure cheat-sheet.
• .claude-plugin/plugin.json — registers it as a Claude Code plugin named loomta.

The skill declares the tooling permission it needs:

Bash(loomta:*)

Note

Grant Bash(loomta:*) so the agent may run loomta … commands, and set LOOMTA_API_KEY in its environment. With those two in place the agent has everything it needs.

A typical agent run

loomta auth:status                                   # 1. key valid?
PID=$(loomta platforms:list \
  | jq -r '.platforms[]|select(.provider=="tiktok").id' | head -n1)  # 2. pick account
loomta platforms:schema "$PID"                       # 3. read limits + settings
ID=$(loomta upload promo.mp4 | jq -r '.id')          # 4. host the media
loomta posts:create -c "Try the app #fyp" -m "$ID" -i "$PID" --mode now   # 5. publish
loomta posts:list                                    # 6. confirm

Rules an agent should encode

• Media must be uploaded first. TikTok rejects local paths and arbitrary URLs — only Loomta-hosted media works. Always upload, then use the returned id.
• One video or 1–35 images, never mixed, per post.
• Read platforms:schema for account-specific values like privacy_level instead of hard-coding them.
• A public post link may lag — TikTok can hold a post in processing briefly after publish.

Failure cheat-sheet

code	Meaning / fix
not_authenticated	No key resolved — set LOOMTA_API_KEY or run auth:login.
media_not_ready	The media ID is wrong or from another workspace.
post_limit_reached	Monthly cap hit (HTTP 409) — the plan needs upgrading.
scheduled_for_required	--mode schedule needs -s <iso>.
invalid_settings	--settings must be a JSON object string.

For the full prose version of this guidance, read the SKILL.md shipped with the package, or the Recipes page.