> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# স্ক্রিপ্টিং ও অটোমেশন

> স্ক্রিপ্ট, CI/CD পাইপলাইন ও অটোমেশন ওয়ার্কফ্লোতে Social media studio CLI ব্যবহার করুন

CLI অটোমেশনের জন্য তৈরি: এটি ডিফল্টভাবে কাঠামোবদ্ধ JSON প্রিন্ট করে, এনভায়রনমেন্ট ভ্যারিয়েবল থেকে ক্রেডেনশিয়াল নেয় এবং স্ট্যান্ডার্ড এক্সিট কোড ব্যবহার করে। প্রতিটি কমান্ড Social media studio-র একটি REST এন্ডপয়েন্টের সাথে ১:১ মেলে, তাই অ্যাপ যা করতে পারে তার সবই স্ক্রিপ্ট করা যায়।

> [!NOTE]
>
> বাইনারিটি `so-me` (ডেভেলপমেন্ট বিল্ড `so-me-dev`)। নিচের সব উদাহরণে `so-me` ব্যবহৃত হয়েছে। সাবকমান্ড কোলন সিনট্যাক্স ব্যবহার করে — `posts:list`, `media:upload`, `agent export-tools`।

## আউটপুট মোড

আউটপুট ফরম্যাটিং গ্লোবাল ফ্ল্যাগ দিয়ে নিয়ন্ত্রিত হয়, যা **প্রতিটি** কমান্ডে প্রযোজ্য। এগুলো বাকি আর্গুমেন্টের পাশে কমান্ড লাইনে দিতে হবে (Commander এগুলোকে গ্লোবাল অপশন হিসেবে গণ্য করে)।

| ফ্ল্যাগ | বিবরণ |
| - | - |
| `--json` | সুসজ্জিত JSON হিসেবে আউটপুট। **এটিই ডিফল্ট** — প্রায় কখনোই আলাদাভাবে দিতে হয় না। |
| `--table` | JSON-এর বদলে মানুষের পড়ার উপযোগী ASCII টেবিলে ফলাফল দেখান। |
| `--verbose` | ব্যর্থ হলে পূর্ণ ত্রুটির বিবরণ (সম্ভব হলে JS স্ট্যাক ট্রেস সহ) প্রিন্ট করুন। |

```bash theme={null}
# JSON is the default
so-me posts:list

# Explicit JSON (same as above)
so-me posts:list --json

# Human-readable table
so-me posts:list --table

# Verbose error output (useful while debugging)
so-me posts:create -c "test" --platform INVALID --verbose
```

> [!WARNING]
>
> `--table` মানুষের জন্য ব্যবহার করুন, স্ক্রিপ্টের জন্য নয়। টেবিল ভিউ লম্বা ফিল্ড ছেঁটে ফেলে এবং কিছু কলাম বেছে নেয়, তাই এটি **মেশিন-পার্সযোগ্য নয়**। অটোমেশনে সবসময় ডিফল্ট JSON `jq`-তে পাইপ করুন।

ডিফল্ট ফরম্যাট CLI কনফিগে (`outputFormat`) সংরক্ষণ করাও যায়, কিন্তু কমান্ড লাইনের `--table` ওই কলের জন্য সবসময় জেতে।

## JSON আউটপুট ও jq

এক্সট্র্যাকশন ও রূপান্তরের জন্য যেকোনো কমান্ড [`jq`](https://jqlang.github.io/jq/)-তে পাইপ করুন।

> [!WARNING]
>
> **তালিকা এন্ডপয়েন্ট পেজ করা এনভেলপ ফেরত দেয়**, সরাসরি অ্যারে নয়। কাঠামো হলো `{ "data": [ ... ], "meta": { ... } }`, তাই আপনাকে `.data[]`-তে ইনডেক্স করতে হবে। একক-অবজেক্ট কমান্ড (`posts:get`, `posts:create`, `posts:update`, …) অবজেক্ট সরাসরি ফেরত দেয়, তাই `.id`-এর মতো ফিল্ড সবচেয়ে উপরের স্তরে থাকে।

```bash theme={null}
# Get the text of every scheduled post (note the .data[] — list responses are paginated)
so-me posts:list --status SCHEDULED | jq '.data[].text'

# Grab the first post's ID
so-me posts:list | jq -r '.data[0].id'

# posts:create returns a single object, so .id is top-level
POST_ID=$(so-me posts:create -c "Hello!" --platform TWITTER | jq -r '.id')
echo "Created post: $POST_ID"

# Count posts by platform
so-me posts:list | jq '.data | group_by(.socialMedia)
  | map({platform: .[0].socialMedia, count: length})'

# Read pagination metadata
so-me posts:list --limit 100 | jq '.meta'
```

## পেজিনেশন

তালিকা কমান্ড দুটি পেজিনেশন ফ্ল্যাগ গ্রহণ করে। তালিকা কমান্ডে `--cursor` বা `--all` ফ্ল্যাগ **নেই** — `--page` বাড়িয়ে পেজ করুন।

| ফ্ল্যাগ | ডিফল্ট | নোট |
| - | - | - |
| `--page <number>` | `1` | ১-ভিত্তিক পেজ নম্বর। |
| `--limit <number>` | কমান্ড অনুযায়ী ভিন্ন | প্রতি পেজে আইটেম। `posts:list` সর্বোচ্চ `100`-এ সীমিত; ডিফল্ট কমান্ডভেদে আলাদা (যেমন `posts:list`/`drafts:list` ডিফল্ট `20`, `accounts:list`/`inbox:list`/`teams:list` ডিফল্ট `50`)। |

```bash theme={null}
# Second page of 50 posts
so-me posts:list --page 2 --limit 50

# Walk every page until an empty data array comes back
page=1
while :; do
  rows=$(so-me posts:list --page "$page" --limit 100 | jq -c '.data')
  [ "$rows" = "[]" ] && break
  echo "$rows" | jq -r '.[].id'
  page=$((page + 1))
done
```

> [!NOTE]
>
> `--all` ফ্ল্যাগ **শুধু** `agent export-tools`-এ আছে, যেখানে এর অর্থ "প্রতিটি টুল ফরম্যাট আউটপুট দিন" — পেজিনেশনের সাথে এর সম্পর্ক নেই।

## শেল স্ক্রিপ্টিং

### তৈরি ও শিডিউল

```bash theme={null}
#!/bin/bash
set -euo pipefail

# Create a post (publishes immediately when no -s/--date is given), then schedule it
POST_ID=$(so-me posts:create \
  -c "Automated post from CI" \
  --platform LINKEDIN \
  | jq -r '.id')

so-me posts:schedule "$POST_ID" \
  -s "$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)"

echo "Post $POST_ID scheduled"
```

> [!NOTE]
>
> `-a/--accounts` না দিলে `posts:create` `--platform` থেকে সোশ্যাল অ্যাকাউন্ট স্বয়ংক্রিয়ভাবে নির্ণয় করে। একাধিক অ্যাকাউন্ট মিললে কমান্ড ইন্টারেক্টিভভাবে জিজ্ঞাসা করে — তাই নন-ইন্টারেক্টিভ CI-তে `-a` দিয়ে সুনির্দিষ্ট অ্যাকাউন্ট ID দিন, অথবা ওই প্ল্যাটফর্মের জন্য একটিমাত্র সংযুক্ত অ্যাকাউন্ট রাখুন।

### ব্যর্থ পোস্ট বাল্ক ডিলিট

```bash theme={null}
#!/bin/bash
set -euo pipefail

# Collect failed post IDs (remember: .data[] for list responses)
FAILED_IDS=$(so-me posts:list --status FAILED --limit 100 | jq -r '.data[].id')

if [ -z "$FAILED_IDS" ]; then
  echo "No failed posts found"
  exit 0
fi

# posts:delete accepts one or many IDs and -y skips the confirmation prompt
echo "$FAILED_IDS" | xargs so-me posts:delete -y
```

### সব ড্রাফট রূপান্তর

```bash theme={null}
#!/bin/bash
set -euo pipefail

# Convert every draft into a scheduled Twitter post
DRAFT_IDS=$(so-me drafts:list --limit 100 | jq -r '.data[].id')

for id in $DRAFT_IDS; do
  so-me drafts:convert "$id" \
    --platform TWITTER \
    --post-type TEXT \
    -s "$(date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ)"
  echo "Converted draft $id"
done
```

## CI-র জন্য প্রমাণীকরণ

CLI এই ক্রমে ক্রেডেনশিয়াল খোঁজে: প্রথমে `--api-key` ফ্ল্যাগ, তারপর `SOME_API_KEY` এনভায়রনমেন্ট ভ্যারিয়েবল, তারপর `auth:login`-এর সংরক্ষিত API কী। অটোমেশনের জন্য এনভায়রনমেন্ট ভ্যারিয়েবল ভালো, যাতে ডিস্কে কিছু লেখা না হয়।

| ভ্যারিয়েবল | সমতুল্য ফ্ল্যাগ | বিবরণ |
| - | - | - |
| `SOME_API_KEY` | `--api-key <key>` | প্রতিটি অনুরোধ প্রমাণীকরণে ব্যবহৃত API কী। |
| `SOME_API_URL` | `--api-url <url>` | API বেস URL। ডিফল্ট `https://api.so-me.studio` (`so-me-dev`-এর ডিফল্ট `http://localhost:8000`)। |

```bash theme={null}
# Authenticate purely from the environment — no auth:login needed
export SOME_API_KEY="sk_live_xxx"
so-me auth:whoami        # verify the key and show the authenticated user + org
so-me posts:list

# Or pass per-command (overrides stored credentials and the env var)
so-me posts:list --api-key sk_live_xxx --api-url https://api.so-me.studio
```

### GitHub Actions

```yaml theme={null}
name: Schedule Weekly Post
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM UTC

jobs:
  post:
    runs-on: ubuntu-latest
    steps:
      - name: Install CLI
        run: npm install -g @social-media-scheduler/cli

      - name: Create and schedule post
        env:
          SOME_API_KEY: ${{ secrets.SOME_API_KEY }}
        run: |
          so-me posts:create \
            -c "Weekly update: check out what's new!" \
            --platform TWITTER \
            -s "$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)"
```

> [!TIP]
>
> আপনার API কী রিপোজিটরি সিক্রেট (`SOME_API_KEY`) হিসেবে রাখুন। CLI এটি স্বয়ংক্রিয়ভাবে এনভায়রনমেন্ট থেকে পড়ে — কখনো ওয়ার্কফ্লো ফাইলে কী বসাবেন না বা রিপোজিটরিতে কমিট করবেন না।

## ত্রুটি সামলানো

### এক্সিট কোড

ব্যর্থ হলে CLI নন-জিরো এক্সিট কোড (`process.exitCode = 1`) সেট করে, ফলে `&&`, `set -e` এবং `if` গার্ড প্রত্যাশিতভাবে কাজ করে।

| কোড | অর্থ |
| - | - |
| `0` | সফল |
| `1` | ত্রুটি — API ত্রুটি, যাচাইকরণ ব্যর্থতা, নেটওয়ার্ক ত্রুটি, ক্রেডেনশিয়াল না থাকা ইত্যাদি। |

### ভার্বোস ত্রুটি

পূর্ণ ত্রুটির বিবরণ, সম্ভব হলে স্ট্যাক ট্রেসসহ, দেখতে `--verbose` ব্যবহার করুন:

```bash theme={null}
so-me posts:create -c "test" --platform INVALID --verbose
```

API ক্লায়েন্ট যেসব সাধারণ ত্রুটির অবস্থা সামনে আনে:

| HTTP স্ট্যাটাস | CLI বার্তা |
| - | - |
| `401` | `Invalid API key. Run 'so-me auth:login' or set SOME_API_KEY.` (বেশি তথ্যবহুল হলে সার্ভারের নির্দিষ্ট বার্তা রাখা হয়) |
| `403` | `Insufficient permissions. Your plan may not include this feature.` |
| `429` | `Rate limit exceeded. Try again later.` |
| নেটওয়ার্ক | `Could not connect to API at <url>. Check your internet connection.` |

### রেট লিমিট সামলানো

রেট-লিমিটেড অনুরোধ (HTTP 429) এক্সিট কোড 1 দিয়ে বেরিয়ে যায়। স্ক্রিপ্টে ব্যাকঅফসহ রিট্রাই লজিক যোগ করুন:

```bash theme={null}
#!/bin/bash
MAX_RETRIES=3
RETRY_DELAY=10

for i in $(seq 1 $MAX_RETRIES); do
  so-me posts:list && break
  echo "Request failed, retrying in ${RETRY_DELAY}s... (attempt $i/$MAX_RETRIES)"
  sleep $RETRY_DELAY
done
```

## এজেন্ট টুল ডেফিনিশন

CLI Social media studio-র টুল ক্যাটালগ AI এজেন্ট ফ্রেমওয়ার্কের ব্যবহারযোগ্য ফরম্যাটে এক্সপোর্ট করতে পারে।
`agent export-tools` MCP সার্ভার থেকে (`POST /mcp`-এ একটি `tools/list` JSON-RPC কল) প্রামাণিক টুল তালিকা **লাইভ** আনে এবং আপনার বেছে নেওয়া ফরম্যাটে আউটপুট দেয়। MCP সার্ভারই একমাত্র সত্যের উৎস, তাই এক্সপোর্ট করা ডেফিনিশন সবসময় লাইভ ক্যাটালগের সাথে মেলে।

```bash theme={null}
so-me agent export-tools --format <format> [options]
```

**-f, --format \<format>** `string`

`mcp`, `openai`, `anthropic`, `hermes`, `openclaw`-এর একটি। `--all` না দিলে আবশ্যক।

**-o, --out \<path>** `string`

আউটপুট একটি ফাইলে লিখুন (এবং সাথের যেকোনো ফাইলও পাশে লিখুন)। পাথ ডিরেক্টরির মতো দেখালে (কোনো ফাইল এক্সটেনশন নেই, বা শেষে স্ল্যাশ আছে) ফরম্যাটের ডিফল্ট ফাইলনাম যুক্ত হয়। বাদ দিলে প্রাথমিক আউটপুট stdout-এ লেখা হয়।

**--all** `boolean` (default: false)

সমর্থিত **প্রতিটি** ফরম্যাট আউটপুট দিন। `--out`-কে ডিরেক্টরি ধরা হয় (ডিফল্ট `./agent-tools`) এবং প্রতিটি ফরম্যাট নিজস্ব সাবডিরেক্টরিতে লেখা হয়।

### সমর্থিত ফরম্যাট

| ফরম্যাট | প্রাথমিক আউটপুট | ডিফল্ট ফাইলনাম | সাথের ফাইল |
| - | - | - | - |
| `mcp` | কাঁচা MCP ক্যাটালগ (`{ "tools": [...] }`) | `tools.mcp.json` | — |
| `openai` | OpenAI Chat Completions ফাংশন-কলিং টুল (`{ "tools": [{ "type": "function", "function": { ... } }] }`) | `tools.openai.json` | — |
| `anthropic` | Anthropic Messages API টুল (`input_schema` সহ ফ্ল্যাট কাঠামো) | `tools.anthropic.json` | — |
| `hermes` | OpenAI-সামঞ্জস্যপূর্ণ টুল JSON (Nous Hermes 4) | `tools.json` | `system_prompt.md`, `tools.md` |
| `openclaw` | Markdown স্কিল রেফারেন্স (গ্রুপ করা টুল টেবিল + পূর্ণ JSON-স্কিমা পরিশিষ্ট) | `tools.md` | — |

### উদাহরণ

```bash MCP (stdout) theme={null}
# Print the raw MCP tool catalog to stdout
so-me agent export-tools --format mcp
```

```bash OpenAI theme={null}
# Write OpenAI-style function definitions to a file
so-me agent export-tools --format openai --out tools.openai.json
```

```bash Anthropic theme={null}
# Write the Anthropic tool-use format
so-me agent export-tools --format anthropic --out tools.anthropic.json
```

```bash Hermes theme={null}
# Hermes kit — writes tools.json plus companion system_prompt.md and tools.md
so-me agent export-tools --format hermes --out ./hermes/
```

```bash OpenClaw theme={null}
# OpenClaw skill reference (markdown). Writes tools.md when --out is a directory
so-me agent export-tools --format openclaw --out tools.md
```

```bash সব ফরম্যাট theme={null}
# Emit every format. Each lands in its own subdirectory under ./agent-tools,
# e.g. ./agent-tools/mcp/tools.mcp.json, ./agent-tools/hermes/tools.json, etc.
so-me agent export-tools --all --out ./agent-tools
```

> [!NOTE]
>
> প্রতিটি ফরম্যাট একই `tools/list` রেসপন্স থেকে তৈরি, তাই এক্সপোর্ট করা ডেফিনিশন লাইভ টুল ক্যাটালগের সাথে সিঙ্কে থাকে। টুলের নাম snake\_case (যেমন `create_post`) এবং CLI-র `resource:verb` কমান্ডগুলোর অনুরূপ। MCP ট্রান্সপোর্টে একই টুলগুলো `mcp_so-me-studio_<tool_name>` (যেমন `mcp_so-me-studio_create_post`) হিসেবে নিবন্ধিত হয়।

## সেলফ-হোস্টেড ইনস্ট্যান্স

CLI-কে ফ্ল্যাগ বা এনভায়রনমেন্ট ভ্যারিয়েবলের মাধ্যমে কাস্টম API URL-এ নির্দেশ করুন:

```bash theme={null}
# Via flag (per command)
so-me posts:list --api-url https://api.yourdomain.com

# Via environment variable (whole session)
export SOME_API_URL=https://api.yourdomain.com
so-me posts:list
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.