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

# Scripts et automatisation

> Utilisez la CLI Social media studio dans des scripts, des pipelines CI/CD et des workflows d'automatisation

La CLI est conçue pour l'automatisation : elle affiche par défaut du JSON structuré, accepte les identifiants via des
variables d'environnement et utilise des codes de sortie standard. Chaque commande correspond 1:1 à un endpoint REST
de Social media studio ; tout ce que fait l'application peut donc être scripté.

> [!NOTE]
>
> Le binaire est `so-me` (la version de développement est `so-me-dev`). Tous les exemples ci-dessous utilisent `so-me`.
> Les sous-commandes utilisent la syntaxe à deux-points — `posts:list`, `media:upload`, `agent export-tools`.

## Modes de sortie

Le format de sortie est contrôlé par des options globales qui s'appliquent à **toutes** les commandes. Elles doivent être
placées sur la ligne de commande avec le reste de vos arguments (Commander les traite comme des options
globales).

| Option | Description |
| - | - |
| `--json` | Sortie en JSON indenté. **C'est la valeur par défaut** — vous avez rarement besoin de l'indiquer explicitement. |
| `--table` | Affiche les résultats sous forme de tableau ASCII lisible plutôt qu'en JSON. |
| `--verbose` | En cas d'échec, affiche le détail complet de l'erreur (y compris la pile d'appels JS lorsqu'elle est disponible). |

```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]
>
> Utilisez `--table` pour les humains, pas pour les scripts. La vue en tableau tronque les champs longs et sélectionne un sous-ensemble
> de colonnes ; elle n'est donc **pas** exploitable par une machine. Dans l'automatisation, transmettez toujours le JSON par défaut à
> `jq`.

Le format par défaut peut aussi être conservé dans la configuration de la CLI (`outputFormat`), mais `--table` sur la
ligne de commande l'emporte toujours pour cette invocation.

## Sortie JSON et jq

Transmettez n'importe quelle commande à [`jq`](https://jqlang.github.io/jq/) pour extraire et transformer les données.

> [!WARNING]
>
> **Les endpoints de liste renvoient une enveloppe paginée**, pas un simple tableau. Sa forme est
> `{ "data": [ ... ], "meta": { ... } }` ; vous devez donc cibler `.data[]`. Les commandes à objet unique
> (`posts:get`, `posts:create`, `posts:update`, …) renvoient directement l'objet, et des
> champs comme `.id` sont donc au premier niveau.

```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'
```

## Pagination

Les commandes de liste acceptent deux options de pagination. Il n'existe **aucune** option `--cursor` ni `--all` sur les commandes de
liste — paginez en incrémentant `--page`.

| Option | Par défaut | Remarques |
| - | - | - |
| `--page <number>` | `1` | Numéro de page, à partir de 1. |
| `--limit <number>` | variable selon la commande | Éléments par page. `posts:list` est plafonné à `100` ; les valeurs par défaut diffèrent selon la commande (par ex. `posts:list`/`drafts:list` valent `20` par défaut, `accounts:list`/`inbox:list`/`teams:list` valent `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]
>
> L'option `--all` existe **uniquement** sur `agent export-tools`, où elle signifie « exporter tous les formats d'outils » — elle n'a
> aucun rapport avec la pagination.

## Scripts shell

### Créer et programmer

```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]
>
> `posts:create` résout automatiquement le compte social à partir de `--platform` lorsque vous ne passez pas
> `-a/--accounts`. Si plusieurs comptes correspondent, la commande pose la question de façon interactive — donc, en
> CI non interactive, passez un ID de compte explicite avec `-a` ou veillez à n'avoir qu'un seul compte connecté
> pour cette plateforme.

### Supprimer en masse les publications en échec

```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
```

### Convertir tous les brouillons

```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
```

## Authentification en CI

La CLI recherche les identifiants dans cet ordre : l'option `--api-key`, puis la variable d'environnement
`SOME_API_KEY`, puis la clé d'API stockée par `auth:login`. Pour l'automatisation, préférez la variable
d'environnement afin que rien ne soit écrit sur le disque.

| Variable | Option équivalente | Description |
| - | - | - |
| `SOME_API_KEY` | `--api-key <key>` | Clé d'API utilisée pour authentifier chaque requête. |
| `SOME_API_URL` | `--api-url <url>` | URL de base de l'API. Par défaut `https://api.so-me.studio` (`so-me-dev` utilise `http://localhost:8000` par défaut). |

```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]
>
> Stockez votre clé d'API comme secret du dépôt (`SOME_API_KEY`). La CLI la lit automatiquement dans l'environnement
> — n'intégrez jamais la clé dans un fichier de workflow et ne la commitez jamais dans le dépôt.

## Gestion des erreurs

### Codes de sortie

En cas d'échec, la CLI définit un code de sortie non nul (`process.exitCode = 1`), de sorte que `&&`, `set -e` et
les gardes `if` se comportent comme prévu.

| Code | Signification |
| - | - |
| `0` | Succès |
| `1` | Erreur — erreur d'API, échec de validation, erreur réseau, identifiants manquants, etc. |

### Erreurs détaillées

Utilisez `--verbose` pour voir le détail complet des erreurs, y compris la pile d'appels lorsqu'elle est disponible :

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

Conditions d'erreur courantes remontées par le client d'API :

| Statut HTTP | Message de la CLI |
| - | - |
| `401` | `Invalid API key. Run 'so-me auth:login' or set SOME_API_KEY.` (les messages propres au serveur sont conservés lorsqu'ils sont plus informatifs) |
| `403` | `Insufficient permissions. Your plan may not include this feature.` |
| `429` | `Rate limit exceeded. Try again later.` |
| réseau | `Could not connect to API at <url>. Check your internet connection.` |

### Gestion des limites de débit

Une requête limitée en débit (HTTP 429) se termine avec le code 1. Dans les scripts, ajoutez une logique de nouvelle tentative avec délai croissant :

```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
```

## Définitions d'outils pour agents

La CLI peut exporter le catalogue d'outils de Social media studio dans des formats exploitables par les frameworks d'agents IA.
`agent export-tools` récupère la liste canonique des outils **en direct** depuis le serveur MCP (un appel JSON-RPC `tools/list`
vers `POST /mcp`) et l'émet dans le format de votre choix. Le serveur MCP est l'unique
source de vérité ; les définitions exportées correspondent donc toujours au catalogue en direct.

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

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

L'un des formats `mcp`, `openai`, `anthropic`, `hermes`, `openclaw`. Obligatoire sauf si `--all` est passé.

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

Écrit la sortie dans un fichier (et écrit les éventuels fichiers complémentaires à côté). Si le chemin ressemble à un
répertoire (pas d'extension, ou barre oblique finale), le nom de fichier par défaut du format est ajouté.
En son absence, la sortie principale est écrite sur la sortie standard.

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

Émet **tous** les formats pris en charge. Traite `--out` comme un répertoire (par défaut `./agent-tools`) et
écrit chaque format dans son propre sous-répertoire.

### Formats pris en charge

| Format | Sortie principale | Nom de fichier par défaut | Fichiers complémentaires |
| - | - | - | - |
| `mcp` | Catalogue MCP brut (`{ "tools": [...] }`) | `tools.mcp.json` | — |
| `openai` | Outils d'appel de fonctions OpenAI Chat Completions (`{ "tools": [{ "type": "function", "function": { ... } }] }`) | `tools.openai.json` | — |
| `anthropic` | Outils de l'API Anthropic Messages (forme à plat avec `input_schema`) | `tools.anthropic.json` | — |
| `hermes` | JSON d'outils compatible OpenAI (Nous Hermes 4) | `tools.json` | `system_prompt.md`, `tools.md` |
| `openclaw` | Référence de skill en Markdown (tableaux d'outils groupés + annexe complète des schémas JSON) | `tools.md` | — |

### Exemples

```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 Tous les formats 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]
>
> Chaque format est dérivé de la même réponse `tools/list` ; les définitions exportées restent donc synchronisées
> avec le catalogue d'outils en direct. Les noms d'outils sont en snake\_case (par ex. `create_post`) et reprennent les commandes
> `resource:verb` de la CLI. Via le transport MCP, les mêmes outils sont enregistrés sous le nom
> `mcp_so-me-studio_<tool_name>` (par ex. `mcp_so-me-studio_create_post`).

## Instances auto-hébergées

Pointez la CLI vers une URL d'API personnalisée via l'option ou la variable d'environnement :

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