A CLI do Kleos: tudo o que se faz no app — gerar, revisar, agendar e medir posts UGC do seu app no TikTok e no Instagram, subir imagens e vídeos, escolher música, conectar contas — pelo terminal ou pelo agente de IA que roda comandos (OpenClaw, Codex, Hermes, CI, cron).

É um cliente do mesmo servidor MCP que o Claude e o Cursor usam (https://mcp.zurc.app/mcp): cada comando é uma chamada de ferramenta, com o mesmo plano, as mesmas cotas e as mesmas regras. Node 22 ou mais novo; nenhuma dependência em tempo de execução.

Começar

Entre pelo navegador — sem chave para criar nem copiar:
```
npx -y kleos-cli login
```
O navegador abre na tela do Kleos: entre com a sua conta, escolha a organização, o projeto e o que a CLI pode fazer (ler, gerar, publicar) e aprove. É OAuth 2.1 com PKCE: a CLI registra-se no servidor de login para a porta local (127.0.0.1:47651, ou outra livre), recebe o código ali, troca pelo token e grava em ~/.config/kleos/config.json (permissão 600). O token renova sozinho. --no-browser só imprime o endereço (SSH). Desconectar de vez: Configurações › Chaves de API › Apps conectados.
Sem gente por perto (servidor, CI, cron), use uma chave de API: quem é dono da organização cria em Configurações › Chaves de API (https://ugc.zurc.app/settings/chaves).
```
npx -y kleos-cli login --key kleos_sk_…
# ou, em servidor/CI:
export KLEOS_API_KEY="kleos_sk_…"
```
KLEOS_API_KEY e KLEOS_MCP_URL no ambiente sobrepõem o arquivo.

Use:

kleos whoami
kleos projects list
kleos posts generate --project habi --agent bia --count 10 --dry-run

Comandos

Comando	O que faz	Ferramenta
`kleos login` / `login --key` / `logout`	entra pelo navegador (OAuth) ou guarda a chave / apaga	`whoami`
`kleos whoami`	conta, plano, camadas e escopos do login ou da chave	`whoami`
`kleos usage`	o que o plano permite e quanto sobra	`get_usage`
`kleos projects list`	projetos (apps)	`list_projects`
`kleos agents list --project <p>`	agentes, contas, aprovações pendentes	`list_agents`
`kleos posts generate`	gera N posts (`--count`, `--format`, `--playbook`, `--at`, `--dry-run`, `--yes`)	`generate_posts`
`kleos posts list`	por período, estado, agente	`list_posts`
`kleos posts show <id>`	slides, legenda, publicações	`get_post`
`kleos posts approve <id>…`	aprova (publica em conta real)	`approve_posts`
`kleos posts schedule <id> --account …`	agenda em conta(s)	`schedule_post`
`kleos week plan`	planeja os próximos dias	`plan_week`
`kleos jobs wait <job_id>`	espera um trabalho da fila	`get_job`
`kleos metrics [--since 7d]`	resultados do período	`get_metrics`
`kleos upload <arquivo\|pasta>…`	sobe imagens e vídeos para a biblioteca (assina, PUT em fluxo com progresso, confirma) e imprime os `media_id`	`upload_media`, `confirm_upload`
`kleos music list` / `import <url>` / `set <post>`	acervo e faixas em alta do TikTok, extrair de link, escolher a música do post	`list_music`, `import_music`, `set_post_music`
`kleos accounts list` / `connect <rede\|conta>`	contas e estado; conectar abre o navegador na autorização da rede (`--wait` espera concluir)	`list_accounts`, `connect_account`
`kleos call <ferramenta> --args '<json>'`	qualquer ferramenta do MCP	—
`kleos mcp`	ponte stdio → HTTP para cliente que só fala stdio	—
`kleos skill install`	instala a skill no Claude Code, Codex, Hermes e OpenClaw	—

kleos <comando> --help mostra as opções e exemplos. O resto do app — editar post, rascunhos do editor, playbooks, produção, estúdio, comentários, time — sai por kleos call <ferramenta>. A lista das ferramentas com parâmetros: https://ugc.zurc.app/llms-full.txt

kleos upload ./fotos --project habi --json     # uploaded[].media_id
kleos call create_post --args '{"project":"habi","agent":"bia","slides":[{"media_id":"…","text":"…"}]}'
kleos accounts connect tiktok --project habi --agent bia --wait

Para agentes e scripts

--json em todo comando; é o padrão quando o stdout não é terminal. O resultado sai no stdout; o erro, no stderr, como {"error": "…", "exit_code": 3, "details": {…}}.

Códigos de saída:

Código	Quando
0	deu certo
1	erro (rede, chave inválida ou login vencido, servidor, trabalho que falhou)
2	uso errado (comando, flag, parâmetro)
3	limite ou cota do plano — não repita em laço
4	falta aprovação humana (gasto grande: rode de novo com `--yes`), escopo da chave ou camada do plano

Nada é interativo sem pedir: gasto grande (mais de 10 posts, ou mais do que sobra no plano) sai com 4 e a estimativa; --yes confirma.
Toda escrita manda uma idempotency_key nova; --idempotency-key fixa uma para repetir com segurança.

Clientes só-stdio

O Claude Desktop e o ChatGPT conectam direto pela URL (https://mcp.zurc.app/mcp, com login). Para cliente que só fala stdio, a ponte usa o login da CLI (kleos login antes) ou a chave:

{
  "mcpServers": {
    "kleos": { "command": "npx", "args": ["-y", "kleos-cli", "mcp"], "env": { "KLEOS_API_KEY": "kleos_sk_…" } }
  }
}

Desenvolvimento

npm test            # vitest, com fetch falso — não chama o servidor
npm run build       # tsc → dist/, e copia ../skills para skills/
npm pack --dry-run  # confere o que entra no pacote
KLEOS_MCP_URL=http://127.0.0.1:3000/mcp node dist/cli.js whoami