> ## 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 e automação

> Use a CLI do Social media studio em scripts, pipelines de CI/CD e fluxos de automação

A CLI foi feita para automação: ela imprime JSON estruturado por padrão, aceita credenciais de
variáveis de ambiente e usa códigos de saída padrão. Cada comando corresponde 1:1 a um endpoint REST do
Social media studio, então tudo o que o app faz pode ser automatizado por script.

> [!NOTE]
>
> O binário é `so-me` (a versão de desenvolvimento é `so-me-dev`). Todos os exemplos abaixo usam `so-me`.
> Os subcomandos usam a sintaxe com dois-pontos: `posts:list`, `media:upload`, `agent export-tools`.

## Modos de saída

A formatação da saída é controlada por flags globais que se aplicam a **todos** os comandos. Elas devem ser
colocadas na linha de comando junto com o restante dos argumentos (o Commander as trata como opções
globais).

| Flag | Descrição |
| - | - |
| `--json` | Saída em JSON formatado. **Este é o padrão**; raramente você precisa passá-la explicitamente. |
| `--table` | Exibe os resultados como uma tabela ASCII legível, em vez de JSON. |
| `--verbose` | Em caso de falha, imprime todos os detalhes do erro (incluindo o stack trace do JS quando disponível). |

```bash theme={null}
# JSON é o padrão
so-me posts:list

# JSON explícito (igual ao anterior)
so-me posts:list --json

# Tabela legível
so-me posts:list --table

# Saída de erro detalhada (útil na depuração)
so-me posts:create -c "test" --platform INVALID --verbose
```

> [!WARNING]
>
> Use `--table` para pessoas, não para scripts. A visualização em tabela trunca campos longos e seleciona um subconjunto
> de colunas, portanto **não** pode ser interpretada por máquina. Na automação, sempre encadeie o JSON padrão com `jq`.

O formato padrão também pode ser persistido na configuração da CLI (`outputFormat`), mas `--table` na
linha de comando sempre prevalece naquela execução.

## Saída JSON e jq

Encadeie qualquer comando com o [`jq`](https://jqlang.github.io/jq/) para extrair e transformar dados.

> [!WARNING]
>
> **Os endpoints de listagem retornam um envelope paginado**, não um array simples. O formato é
> `{ "data": [ ... ], "meta": { ... } }`, então você precisa acessar `.data[]`. Os comandos de objeto único
> (`posts:get`, `posts:create`, `posts:update` etc.) retornam o objeto diretamente, então
> campos como `.id` ficam no nível superior.

```bash theme={null}
# Obter o texto de cada post agendado (note o .data[]: as respostas de listagem são paginadas)
so-me posts:list --status SCHEDULED | jq '.data[].text'

# Pegar o ID do primeiro post
so-me posts:list | jq -r '.data[0].id'

# posts:create retorna um único objeto, então .id fica no nível superior
POST_ID=$(so-me posts:create -c "Hello!" --platform TWITTER | jq -r '.id')
echo "Created post: $POST_ID"

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

# Ler os metadados de paginação
so-me posts:list --limit 100 | jq '.meta'
```

## Paginação

Os comandos de listagem aceitam duas flags de paginação. **Não** existe `--cursor` nem `--all` nos comandos
de listagem; pagine incrementando `--page`.

| Flag | Padrão | Observações |
| - | - | - |
| `--page <number>` | `1` | Número da página, começando em 1. |
| `--limit <number>` | varia conforme o comando | Itens por página. `posts:list` tem limite de `100`; os padrões variam por comando (por exemplo, `posts:list`/`drafts:list` usam `20`, `accounts:list`/`inbox:list`/`teams:list` usam `50`). |

```bash theme={null}
# Segunda página de 50 posts
so-me posts:list --page 2 --limit 50

# Percorrer todas as páginas até retornar um array data vazio
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]
>
> A flag `--all` existe **somente** em `agent export-tools`, onde significa "emitir todos os formatos de
> ferramentas"; ela não tem relação com paginação.

## Scripts de shell

### Criar e agendar

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

# Cria um post (publica imediatamente quando -s/--date não é informada) e depois o agenda
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` resolve a conta social automaticamente a partir de `--platform` quando você não passa
> `-a/--accounts`. Se várias contas corresponderem, o comando pede uma escolha interativa; portanto, em
> CI não interativo, passe um ID de conta explícito com `-a` ou conte com uma única conta conectada
> para essa plataforma.

### Excluir em lote posts com falha

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

# Coleta os IDs dos posts com falha (lembre-se: .data[] nas respostas de listagem)
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 aceita um ou vários IDs e -y ignora a confirmação
echo "$FAILED_IDS" | xargs so-me posts:delete -y
```

### Converter todos os rascunhos

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

# Converte cada rascunho em um post agendado do Twitter
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
```

## Autenticação para CI

A CLI procura credenciais nesta ordem: a flag `--api-key`, depois a variável de ambiente `SOME_API_KEY`
e, por fim, a chave de API armazenada por `auth:login`. Na automação, prefira a variável de ambiente para que nada seja gravado em disco.

| Variável | Flag equivalente | Descrição |
| - | - | - |
| `SOME_API_KEY` | `--api-key <key>` | Chave de API usada para autenticar cada requisição. |
| `SOME_API_URL` | `--api-url <url>` | URL base da API. O padrão é `https://api.so-me.studio` (`so-me-dev` usa `http://localhost:8000`). |

```bash theme={null}
# Autenticar somente pelo ambiente, sem precisar de auth:login
export SOME_API_KEY="sk_live_xxx"
so-me auth:whoami        # verifica a chave e mostra o usuário autenticado + a organização
so-me posts:list

# Ou passar por comando (substitui as credenciais armazenadas e a variável de ambiente)
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]
>
> Armazene a sua chave de API como um segredo do repositório (`SOME_API_KEY`). A CLI a lê do ambiente
> automaticamente; nunca coloque a chave diretamente em um arquivo de workflow nem a faça commit no repositório.

## Tratamento de erros

### Códigos de saída

Em caso de falha, a CLI define um código de saída diferente de zero (`process.exitCode = 1`), de modo que `&&`, `set -e` e
condicionais `if` se comportam como esperado.

| Código | Significado |
| - | - |
| `0` | Sucesso |
| `1` | Erro: erro da API, falha de validação, erro de rede, credenciais ausentes etc. |

### Erros detalhados

Use `--verbose` para ver todos os detalhes do erro, incluindo o stack trace quando houver:

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

Condições de erro comuns expostas pelo cliente da API:

| Status HTTP | Mensagem da CLI |
| - | - |
| `401` | `Invalid API key. Run 'so-me auth:login' or set SOME_API_KEY.` (mensagens específicas do servidor são preservadas quando forem mais informativas) |
| `403` | `Insufficient permissions. Your plan may not include this feature.` |
| `429` | `Rate limit exceeded. Try again later.` |
| rede | `Could not connect to API at <url>. Check your internet connection.` |

### Tratamento de limite de taxa

Uma requisição limitada por taxa (HTTP 429) termina com código 1. Em scripts, adicione uma lógica de nova tentativa com espera crescente:

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

## Definições de ferramentas para agentes

A CLI pode exportar o catálogo de ferramentas do Social media studio em formatos consumíveis por frameworks de agentes de IA.
`agent export-tools` busca a lista canônica de ferramentas **ao vivo** no servidor MCP (uma chamada JSON-RPC `tools/list`
para `POST /mcp`) e a emite no formato que você escolher. O servidor MCP é a única
fonte da verdade, então as definições exportadas sempre correspondem ao catálogo atual.

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

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

Um entre `mcp`, `openai`, `anthropic`, `hermes`, `openclaw`. Obrigatório, a menos que `--all` seja passada.

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

Grava a saída em um arquivo (e grava quaisquer arquivos complementares ao lado dele). Se o caminho parecer um
diretório (sem extensão de arquivo ou com barra no final), o nome de arquivo padrão do formato é acrescentado.
Quando omitida, a saída principal é gravada na saída padrão (stdout).

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

Emite **todos** os formatos compatíveis. Trata `--out` como um diretório (padrão `./agent-tools`) e
grava cada formato em seu próprio subdiretório.

### Formatos compatíveis

| Formato | Saída principal | Nome de arquivo padrão | Arquivos complementares |
| - | - | - | - |
| `mcp` | Catálogo MCP bruto (`{ "tools": [...] }`) | `tools.mcp.json` | — |
| `openai` | Ferramentas de function calling da OpenAI Chat Completions (`{ "tools": [{ "type": "function", "function": { ... } }] }`) | `tools.openai.json` | — |
| `anthropic` | Ferramentas da Anthropic Messages API (formato plano com `input_schema`) | `tools.anthropic.json` | — |
| `hermes` | JSON de ferramentas compatível com a OpenAI (Nous Hermes 4) | `tools.json` | `system_prompt.md`, `tools.md` |
| `openclaw` | Referência de skill em Markdown (tabelas de ferramentas agrupadas + apêndice completo de JSON Schema) | `tools.md` | — |

### Exemplos

```bash MCP (stdout) theme={null}
# Imprimir o catálogo bruto de ferramentas MCP na saída padrão
so-me agent export-tools --format mcp
```

```bash OpenAI theme={null}
# Gravar as definições de função no estilo OpenAI em um arquivo
so-me agent export-tools --format openai --out tools.openai.json
```

```bash Anthropic theme={null}
# Gravar o formato de tool use da Anthropic
so-me agent export-tools --format anthropic --out tools.anthropic.json
```

```bash Hermes theme={null}
# Kit Hermes: grava tools.json e os arquivos complementares system_prompt.md e tools.md
so-me agent export-tools --format hermes --out ./hermes/
```

```bash OpenClaw theme={null}
# Referência de skill do OpenClaw (markdown). Grava tools.md quando --out é um diretório
so-me agent export-tools --format openclaw --out tools.md
```

```bash Todos os formatos theme={null}
# Emitir todos os formatos. Cada um vai para o próprio subdiretório em ./agent-tools,
# por exemplo ./agent-tools/mcp/tools.mcp.json, ./agent-tools/hermes/tools.json etc.
so-me agent export-tools --all --out ./agent-tools
```

> [!NOTE]
>
> Todos os formatos são derivados da mesma resposta `tools/list`, portanto as definições exportadas ficam sincronizadas
> com o catálogo de ferramentas atual. Os nomes das ferramentas usam snake\_case (por exemplo, `create_post`) e espelham os comandos
> `resource:verb` da CLI. No transporte MCP, as mesmas ferramentas são registradas como
> `mcp_so-me-studio_<tool_name>` (por exemplo, `mcp_so-me-studio_create_post`).

## Instâncias auto-hospedadas

Aponte a CLI para uma URL de API personalizada por meio da flag ou da variável de ambiente:

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

# Pela variável de ambiente (sessão inteira)
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.