CLI

O Gennia CLI (@gennia/cli) é o comando gennia que você roda no terminal. Três coisas que ele resolve:

gennia mcp install instala o servidor MCP em todos os clientes AI da sua máquina (Cursor, Claude Code, Claude Desktop) num único comando.
gennia api é o escape hatch pra qualquer endpoint da Public API — útil pra scripts, CI, automações em bash.
gennia knowledge upload, gennia skills upload, gennia hub upload-logo resolvem o que o MCP não consegue: file uploads multipart.

CLI e MCP se complementam. O MCP é pra chat conversacional em IDE / app; o CLI é pra scripts, agentes que vivem no shell, e operações em lote. A mesma API por baixo, o mesmo @gennia/sdk internamente.

Instalação

Requer Node 20+.

Global (recomendado)
npx (sem instalar)

npm install -g @gennia/cli
gennia --version
# 0.3.1

npx -y @gennia/cli@latest <comando>

Mais lento que a versão global (baixa do npm em cada chamada), mas zero pegada na máquina.

Autenticação

gennia auth login

Pede a sua API key (gsk_...) — você cola, ela vira ******** durante o paste (raw-mode masking, não vaza no histórico). A credencial fica em ~/.config/gennia/config.json com permissão 0600.

Default = produção (api.gennia.ai). Se sua key foi gerada num workspace de dev/staging, passe --base-url:

gennia auth login --base-url=https://api.dev.gennia.ai

Gere a key dentro do Studio: abra seu workspace, Settings → API Keys. Para confirmar:

gennia auth whoami

# Workspace:        86072856-d8e0-41ef-9462-66bafce30536
# API key ID:       ae48b1e6-cc58-4b76-a554-d02f8229cc73
# Base URL:         https://api.dev.gennia.ai
# Credential from:  config

A hierarquia de resolução é --api-key flag → GENNIA_API_KEY env → arquivo de config.

Instalar o MCP nos seus clientes AI

gennia mcp install

Esse é o comando marquise. Detecta automaticamente quais clientes AI você tem instalados (Claude Code, Cursor, Claude Desktop) e escreve a configuração do servidor MCP no arquivo certo de cada um. Também copia um SKILL.md no diretório de skills do Claude Code (assim o agente “sabe” sobre Gennia mesmo em sessões novas). Flags úteis pra modo não-interativo (CI, scripts):

gennia mcp install --target=claude-code,cursor --yes --json
gennia mcp install --dry-run                              # preview, não escreve
gennia mcp install --update                               # sobrescreve entrada existente
gennia mcp install --no-skill                             # não escreve o SKILL.md

Comandos relacionados:

gennia mcp list      # mostra onde o gennia está instalado e o status de cada um
gennia mcp status    # diagnóstico: Node version, API reachable, npx no PATH, etc.
gennia mcp uninstall # remove de todos os clientes (ou --target=<um>)

Escape hatch: `gennia api`

Cobre qualquer endpoint da Public API. O CLI não precisa codar wrapper pra cada operação — gennia api METHOD /path resolve.

# Listar
gennia api GET /agents --limit 5

# Criar
gennia api POST /agents --body '{"name":"Bot Vendas","categories":["sales"]}'

# Body de arquivo
gennia api POST /agents --body @./payload.json

# Body de stdin
echo '{"name":"Test"}' | gennia api POST /agents --body -

# Query params
gennia api GET /agents --query 'limit=20&status=active'

# Auto-paginar (vai concatenando items[] até acabar)
gennia api GET /agents --all > agents.json

# Pipe pra jq
gennia api GET /agents --all | jq -r '.items[].publicId' | while read id; do
  gennia api PATCH /agents/$id --body '{"categories":["sales"]}'
done

Caminhos podem ser:

Relativos: /agents → vira https://api.gennia.ai/public/api/v1/agents
Absolutos com prefixo: /public/api/v1/agents
URL completa: https://api.dev.gennia.ai/public/api/v1/agents

Upload de arquivos

Três endpoints da API recebem multipart/form-data em vez de JSON. O CLI tem comandos dedicados:

# Knowledge source (PDF, TXT, CSV, DOCX, MD)
gennia knowledge upload ./manual.pdf --name "Manual Q4 2026"
gennia knowledge upload ./dados.csv --metadata '{"name":"Vendas 2026","description":"export raw"}'

# Skill bundle (ZIP, .skill ou SKILL.md standalone)
gennia skills upload ./minha-skill.zip

# Logo do hub
gennia hub upload-logo ./logo.png --type=horizontal   # ou icon | email | banner

Todos suportam --json e exit codes padronizados (veja abaixo).

Contrato de output

Todo comando do CLI segue as mesmas regras pra ser confiável em scripts e seguro pra agentes IA:

stdout = dados. JSON estável por padrão fora de TTY, formatado bonito em TTY. Force JSON com --json.
stderr = humanos. Banners, progresso, hints. Suprima com --quiet.
NO_COLOR=1 desliga as cores ANSI em qualquer comando.

Exit codes com significado:

Code	Quando
0	Sucesso
1	Erro genérico ou 5xx do servidor
2	Erro de uso (flag inválida, falta TTY pra prompt)
3	Não encontrado (HTTP 404)
4	Não autenticado (HTTP 401/403, sem credencial)
5	Conflito (HTTP 409, configuração existente)

Erros sempre estruturados. Em modo --json:

{
  "error": {
    "code": "config_conflict",
    "message": "An existing MCP entry differs from what would be installed.",
    "hint": "Re-run with --update to overwrite, or `gennia mcp uninstall` first."
  }
}

Sem hang interativo. Todo comando que precisa de input detecta non-TTY e falha imediato com hint pra passar a flag faltando.

Variáveis de ambiente

Variável	Default	Efeito
`GENNIA_API_KEY`	—	API key do workspace (`gsk_...`)
`GENNIA_BASE_URL`	`https://api.gennia.ai`	Override pra dev / backend local
`GENNIA_CONFIG_DIR`	`$XDG_CONFIG_HOME/gennia` ou `~/.config/gennia`	Onde o `config.json` mora
`NO_COLOR`	unset	Desabilita ANSI colors

Skill file embarcado

Toda instalação do CLI inclui um skill.md (~6 KB) que gennia mcp install copia pra ~/.claude/skills/gennia/SKILL.md (e equivalente no Cursor). É um markdown que ensina o agente IA:

Quando reachar pelas tools MCP vs gennia api no shell
Mapeamento de domínios → endpoints
Workflows comuns (lista todos os agentes, atualiza em lote, etc.)
Cuidados (uploads precisam de file_path, mutações destrutivas pedem confirmação)

O resultado: na primeira sessão de qualquer cliente AI na sua máquina, ele já “sabe” sobre Gennia sem você precisar explicar.

Atualizar

npm install -g @gennia/cli@latest
gennia --version

Ou veja releases no GitHub. Os pacotes são assinados com provenance SLSA (badge “Built and signed on GitHub Actions” no npm).

Source

github.com/Gennia-Tech-Group/gennia-cli — MIT, public.

Próximos passos

Instalar o MCP

O CLI já instala o MCP via gennia mcp install, mas vale ler como o servidor MCP funciona e o que você ganha com ele.

Referência completa

Cada endpoint que gennia api chama está documentado aqui com schemas e try-it-out.

Começando

Convenções

Agents

Threads

Hub

Instalação

Autenticação

Instalar o MCP nos seus clientes AI

Escape hatch: `gennia api`

Upload de arquivos

Contrato de output

Variáveis de ambiente

Skill file embarcado

Atualizar

Source

Próximos passos

Instalar o MCP

Referência completa

​Instalação

​Autenticação

​Instalar o MCP nos seus clientes AI

​Escape hatch: gennia api

​Upload de arquivos

​Contrato de output

​Variáveis de ambiente

​Skill file embarcado

​Atualizar

​Source

​Próximos passos

Instalar o MCP

Referência completa

Instalação

Autenticação

Instalar o MCP nos seus clientes AI

Escape hatch: `gennia api`

Upload de arquivos

Contrato de output

Variáveis de ambiente

Skill file embarcado

Atualizar

Source

Próximos passos