SDK & CLI Guide
Use the ReelsFarm TypeScript SDK and reelsfarm CLI in custom agents, shell-capable coding agents, and CI workflows.
Install
npm install @reelsfarm/mcp-clientnpm install -g @reelsfarm/mcp-clientThe current SDK version is 3.9.0 and requires Node 20 or newer. The current MCP server is 3.17.0, contract 2026-11-01.1. Update from SDK 3.6 or older: those versions confirm through reelsfarm_confirm_action, which servers since 3.7 reject.
Credentials
Credential resolution order is constructor options, environment variables, then the CLI config file at ~/.reelsfarm/config.json. Set REELSFARM_CONFIG_DIR to use another config directory.
reelsfarm login --api-key rfmcp_xxx
reelsfarm whoamiTypeScript client
import { ReelsFarmClient } from "@reelsfarm/mcp-client";
const rf = new ReelsFarmClient({
apiKey: process.env.REELSFARM_API_KEY,
});
const avatar = await rf.avatars.generate({
prompt: "Woman in her 30s, casual outfit, smartphone selfie style",
model: "gpt-image-2.5-sunburst",
aspectRatio: "9:16",
quality: "high",
});
if ("wait" in avatar) {
const result = await avatar.wait();
console.log(result);
}
await rf.close();- Use rf.account for account, credits, queue, and server info.
- Use rf.avatars, rf.productScenes, rf.slideshows, rf.videos, and rf.hooks for generation.
- Use rf.slideshows.recreate, searchPhotos, savePhotos, saveFormat, and createBatch for Recreate, slide photos, and batches of slideshows.
- Use rf.productContexts to describe a product once and reuse it in slideshows and Recreate.
- Use rf.posts and rf.social for scheduling, publishing, and connected accounts.
- Use rf.raw.callTool when you need direct MCP tool access.
CLI agent mode
Use --agent or REELSFARM_AGENT_MODE=1 when an AI agent is reading command output. Agent mode returns strict JSON envelopes on stdout. It does not mix tables or human narration into output.
reelsfarm agent status
reelsfarm agent commands
reelsfarm social connected --agentreelsfarm posts preflight \
--content-type SLIDESHOW \
--content-id 11111111-1111-4111-8111-111111111111 \
--publish-format VIDEO \
--connection-ids 22222222-2222-4222-8222-222222222222 \
--agent
reelsfarm posts schedule \
--content-type SLIDESHOW \
--content-id 11111111-1111-4111-8111-111111111111 \
--when 2026-10-01T15:00:00Z \
--publish-format VIDEO \
--platforms-json '[{"platform":"TIKTOK","connectionId":"22222222-2222-4222-8222-222222222222","tiktokPublishMode":"DIRECT","tiktokPrivacyLevel":"PUBLIC_TO_EVERYONE","tiktokIsAigc":true}]' \
--agent
reelsfarm confirm conf_123 --tool reelsfarm_confirm_schedule_post --agentA prepared result names its confirmationTool. Pass it to reelsfarm confirm with --tool. Each confirmation tool runs only the operation it was prepared for.
--yes and --dry-run
- Agent mode controls JSON output. Review returns confirmation payloads. Creator and Autopilot can execute allowed actions immediately; the CLI output mode does not change the connection policy.
- Pass --yes only when the user has already approved immediate execution.
- --dry-run always wins over --yes.
- Direct write commands such as assets import and slideshows create require --yes in agent mode.
- Direct destructive commands such as posts cancel and logout require --yes in agent mode.
