# SDK e CLI

> Os pacotes npm @praeko/sdk (cliente JavaScript) e @praeko/cli (comando praeko): instalar com npm, yarn, pnpm ou bun, início rápido, repetição segura com idempotencyKey e comandos.

Fonte: https://praeko.app/docs/sdk

Node 22 ou mais novo · Sem dependências · Só ESM

Dois pacotes no npm: `@praeko/sdk`, para chamar a API do seu código, e `@praeko/cli`, o comando `praeko` no terminal.

## Instalar

### SDK, no seu projeto

**npm**

```bash
npm install @praeko/sdk
```

**yarn**

```bash
yarn add @praeko/sdk
```

**pnpm**

```bash
pnpm add @praeko/sdk
```

**bun**

```bash
bun add @praeko/sdk
```

### CLI, no terminal

**npm**

```bash
npm install -g @praeko/cli
```

**yarn**

```bash
yarn global add @praeko/cli
```

**pnpm**

```bash
pnpm add -g @praeko/cli
```

**bun**

```bash
bun add -g @praeko/cli
```

**Sem instalar o CLI**

```bash
npx @praeko/cli --help
pnpm dlx @praeko/cli --help
bunx @praeko/cli --help
yarn dlx @praeko/cli --help   # yarn 2 ou mais novo
```

O SDK não tem dependências, traz os tipos do TypeScript e roda em Node 22 ou mais novo, Cloudflare Workers, Deno, Bun e no navegador. O CLI é publicado com o SDK embutido: não há nada mais para instalar. O único comando é `praeko`.

## Início rápido do SDK

Crie uma chave de API no painel (ou com `praeko key create`) e guarde em `PRAEKO_KEY`. Nunca coloque a chave no código nem no navegador.

**JavaScript (Node)**

```js
import { Praeko } from "@praeko/sdk";
import { uploadFile } from "@praeko/sdk/node"; // só Node: envia o arquivo do disco em partes

const praeko = new Praeko({ url: "https://praeko.app", key: process.env.PRAEKO_KEY });

const video = await uploadFile(praeko, "./video.mp4", { type: "video", onProgress: (done, total) => {} });
const post = await praeko.posts.create({
  title: "Meu vídeo",
  media: { video: video.id },
  texts: { youtube: { title: "Meu vídeo", text: "Descrição do vídeo" } },
  items: [{ network: "youtube", queue: true }],
});
console.log(post.id);
```

Fora do Node (Workers, navegador), passe um `Uint8Array`, um `Blob` ou `{ size, read(start, n) }` para `praeko.media.upload(source, { type, name, mime })`. O envio escolhe sozinho entre uma requisição só e várias partes, conforme o tamanho. No navegador, na mesma origem do painel, use `{ cookies: true }` no lugar da chave.

## Tentativas e repetição segura

| Chamada | Repete sozinha em falha de rede, `429` e `5xx`? |
|---|---|
| `GET` e envio de partes de mídia | Sim, até 3 tentativas (mude com `retries`). |
| `POST`, `PATCH` e `DELETE` | Não, para não duplicar. Com a opção `idempotencyKey`, sim: o SDK reenvia com a mesma chave. |

**Criar um post sem risco de duplicar**

```js
// true: o SDK gera um UUID e o reutiliza em todas as tentativas desta chamada
const post = await praeko.posts.create({ title, media: { video: video.id }, texts, items }, { idempotencyKey: true });

// ou escolha a chave, por exemplo a de um job seu
await praeko.webhooks.create({ url: "https://example.com/hooks/praeko", idempotencyKey: `hook-${jobId}` });
```

Veja as regras do cabeçalho em [Repetir uma requisição](https://praeko.app/docs/guides/idempotency). Erros viram `PraekoError`, com `status`, `code` (estável, em inglês), `message` e `details`:

**Erros**

```js
import { PraekoError } from "@praeko/sdk";
try { await praeko.posts.get("nao-existe"); }
catch (e) { if (e instanceof PraekoError && e.code === "not_found") { /* … */ } else throw e; }
```

As rotas e os códigos de erro também saem tipados em `@praeko/sdk/contract` (`ROUTES`, `ERROR_CODES`).

## Comandos da CLI

Aponte o CLI para o serviço com `--server https://praeko.app` (ou `PRAEKO_SERVER`) e dê a chave em `PRAEKO_KEY`. Nada é enviado, hospedado ou agendado sem `--send`: sem ele, `post` só simula. As mensagens da CLI são em inglês (CLI 0.4.0).

| Comando | Faz |
|---|---|
| `praeko post <pasta> --queue`, `--when …` ou `--draft` | Cria um post a partir de uma pasta com `publication.json`, o vídeo e a capa (precisa de um `praeko.json` na pasta atual ou acima). Simula, a não ser com `--send`. |
| `praeko posts` | Lista posts por `--state`, `--channel`, `--tag`, `--limit`. |
| `praeko calendar` | Itens agendados e vagas livres, com `--from` e `--to`. |
| `praeko slots <rede> [dia hora …]` | Mostra ou troca os horários semanais. |
| `praeko publish-now <id> [--idempotency-key K]` | Tira da fila e publica agora. A chave evita publicar duas vezes se você repetir o comando. |
| `praeko channels` | O que está conectado. |
| `praeko insights` | Métricas, com `--days`, `--channel`, `--compare`, `--json`. |
| `praeko content` | Tudo o que já foi publicado. |
| `praeko youtube videos`, `edit`, `comments`, `reply` | Vídeos do canal, edição de título e descrição, comentários sem resposta e respostas. Edição e resposta simulam até `--send`. |
| `praeko key create`, `list`, `revoke` | Chaves de API (precisa de uma chave admin). |
| `praeko webhook list`, `create --url … [--idempotency-key K]`, `test`, `deliveries`, `retry` | Webhooks de saída, escopo admin. O segredo aparece uma vez. |
| `praeko usage` e `praeko usage log` | Uso da API e log das requisições dos últimos 30 dias. |
| `praeko help` | A lista completa, com todas as opções. |

**Terminal**

```bash
export PRAEKO_KEY="praeko_…"
export PRAEKO_SERVER="https://praeko.app"

praeko --version
praeko channels
praeko post ./meu-video --queue          # simula
praeko post ./meu-video --queue --send   # agenda de verdade
```

Códigos de saída: `0` sucesso; `1` erro (mensagem em inglês no stderr); `2` comando ou argumento inválido (mostra a ajuda). O CLI não repete sozinho: `--idempotency-key` serve a quem roda o comando de novo, por exemplo num script com tentativas.

## Chave e variáveis de ambiente

| Variável | Para quê |
|---|---|
| `PRAEKO_KEY` | A chave de API. |
| `PRAEKO_SERVER` | O endereço do serviço, `https://praeko.app`. Dispensa `--server`. |
| `PRAEKO_SECRETS` | Outro caminho para o arquivo de segredos (o padrão é `~/.config/praeko/secrets.json`, modo 600). |
| `PRAEKO_NO_KEYCHAIN` | `1` ignora o Chaveiro do macOS. |

Sem `PRAEKO_KEY`, o CLI procura a chave no Chaveiro do macOS (só no Mac) e no arquivo de segredos. No Linux e no Windows valem a variável e o arquivo.

## Versões

[SemVer](https://semver.org/lang/pt-BR/). Enquanto a versão for `0.x`, uma mudança incompatível pode sair numa versão menor, e todas constam no `CHANGELOG.md` de cada pacote. O `praeko studio` entrega ao [Praeko Studio](https://praeko.app/docs/studio) (`@praeko/studio`), instalado à parte.

> **Nomes antigos** O comando `arauto` saiu do pacote na CLI 0.1.1: use `praeko` (quem usou a 0.1.0 pode rodar `npx -p @praeko/cli praeko`). Desde a CLI 0.4.0 (08/11/2026) a CLI só aceita comandos, opções e arquivos em inglês (`publication.json`, `PRAEKO_SECRETS`, `PRAEKO_NO_KEYCHAIN`; veja o [changelog](https://praeko.app/docs/changelog)); a variável `ARAUTO_CHAVE` ainda é lida, e `Arauto` segue como apelido no SDK. Os nomes em português do SDK (`chave`, `enviarArquivo`…) são apelidos descontinuados e saem numa versão futura.