Saltar para o conteúdo principal
O Gennia CLI (@gennia/cli) é o comando gennia que você roda no terminal. Três coisas que ele resolve:
  1. gennia mcp install instala o servidor MCP em todos os clientes AI da sua máquina (Cursor, Claude Code, Claude Desktop) num único comando.
  2. gennia api é o escape hatch pra qualquer endpoint da Public API — útil pra scripts, CI, automações em bash.
  3. 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+. 
npm install -g @gennia/cli
gennia --version
# 0.3.1

​
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:
    CodeQuando
    0Sucesso
    1Erro genérico ou 5xx do servidor
    2Erro de uso (flag inválida, falta TTY pra prompt)
    3Não encontrado (HTTP 404)
    4Não autenticado (HTTP 401/403, sem credencial)
    5Conflito (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ávelDefaultEfeito
GENNIA_API_KEY—API key do workspace (gsk_...)
GENNIA_BASE_URLhttps://api.gennia.aiOverride pra dev / backend local
GENNIA_CONFIG_DIR$XDG_CONFIG_HOME/gennia ou ~/.config/genniaOnde o config.json mora
NO_COLORunsetDesabilita 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.