# SDK & CLI Guide

Use the ReelsFarm TypeScript SDK and reelsfarm CLI in custom agents, shell-capable coding agents, and CI workflows.

Canonical: /docs/agents.md

## Install

**SDK**
```bash
npm install @reelsfarm/mcp-client
```

**CLI**
```bash
npm install -g @reelsfarm/mcp-client
```

The current SDK repo version is 0.1.0. It requires Node 20 or newer.

## 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.

**Login**
```bash
reelsfarm login --api-key rfmcp_xxx
reelsfarm whoami
```

## TypeScript client

**Generate an avatar and wait**
```ts
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: "nano-banana-pro",
});

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, rf.hooks, and rf.aiClones for generation.
- 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.

**Discovery first**
```bash
reelsfarm agent status
reelsfarm agent commands
reelsfarm social connected --agent
```

**Prepare, review, confirm**
```bash
reelsfarm posts schedule \
  --content-type SLIDESHOW \
  --content-id sl_123 \
  --when 2026-07-01T15:00:00Z \
  --platforms tiktok:conn_123 \
  --agent

reelsfarm confirm conf_123 --agent
```

## --yes and --dry-run

- In agent mode, prepared actions return confirmation payloads by default.
- Pass --yes only when the user has already approved immediate execution.
- --dry-run always wins over --yes.
- Direct write commands such as assets import, slideshows create, and webhooks create require --yes in agent mode.
- Direct destructive commands such as posts cancel, webhooks delete, and logout require --yes in agent mode.