> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gennia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> O comando gennia. Auth, instalação do MCP em 1 comando, e escape hatch direto pra qualquer endpoint da Public API.

O **Gennia CLI** ([`@gennia/cli`](https://www.npmjs.com/package/@gennia/cli)) é o comando `gennia` que você roda no terminal. Três coisas que ele resolve:

1. **`gennia mcp install`** instala o [servidor MCP](/pt/api-reference/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.

<Note>
  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.
</Note>

## Instalação

Requer **Node 20+**.

<Tabs>
  <Tab title="Global (recomendado)">
    ```bash theme={null}
    npm install -g @gennia/cli
    gennia --version
    # 0.3.1
    ```
  </Tab>

  <Tab title="npx (sem instalar)">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## Autenticação

```bash theme={null}
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`.

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

  ```bash theme={null}
  gennia auth login --base-url=https://api.dev.gennia.ai
  ```
</Tip>

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

Para confirmar:

```bash theme={null}
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

```bash theme={null}
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):

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
# 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:

```bash theme={null}
# 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`:

  ```json theme={null}
  {
    "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

```bash theme={null}
npm install -g @gennia/cli@latest
gennia --version
```

Ou veja [releases no GitHub](https://github.com/Gennia-Tech-Group/gennia-cli/releases). Os pacotes são assinados com [provenance SLSA](https://slsa.dev) (badge "Built and signed on GitHub Actions" no npm).

## Source

[github.com/Gennia-Tech-Group/gennia-cli](https://github.com/Gennia-Tech-Group/gennia-cli) — MIT, public.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Instalar o MCP" icon="plug" href="/pt/api-reference/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.
  </Card>

  <Card title="Referência completa" icon="book" href="/pt/api-reference/introduction">
    Cada endpoint que `gennia api` chama está documentado aqui com schemas e try-it-out.
  </Card>
</CardGroup>