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

# Instalação e Configuração

> Aprenda a instalar o ChatCLI e a configurar suas chaves de API para começar a usar.

## Pré-requisitos

<CardGroup cols={3}>
  <Card title="Git" icon="code-branch">
    Necessário para clonar o repositório e para que o Go baixe dependências.
  </Card>

  <Card title="Go 1.27+" icon="golang">
    Apenas para `go install` ou compilação do código-fonte.
  </Card>

  <Card title="API Key ou OAuth" icon="key">
    Chave de API de um provedor LLM **ou** conta com plano ativo para OAuth.
  </Card>
</CardGroup>

***

## 1. Instalação

<Tabs>
  <Tab title="Homebrew (Recomendado)">
    A maneira mais fácil para **macOS** e **Linux**. Instala e atualiza automaticamente.

    ```bash theme={"system"}
    brew tap diillson/chatcli
    brew install chatcli
    ```

    Para atualizar:

    ```bash theme={"system"}
    brew upgrade chatcli
    ```

    <Tip>
      Suporta **macOS** (Apple Silicon e Intel) e **Linux** (amd64). A fórmula é atualizada automaticamente a cada release.
    </Tip>
  </Tab>

  <Tab title="Binário">
    Baixe o binário para seu sistema diretamente da [página de Releases](https://github.com/diillson/chatcli/releases).

    ```bash theme={"system"}
    # Linux/macOS — ajuste o nome do arquivo conforme o release
    chmod +x chatcli
    sudo mv chatcli /usr/local/bin/
    ```

    <Tip>
      Disponível para **Linux**, **macOS** e **Windows** em arquiteturas **amd64** e **arm64**.
    </Tip>
  </Tab>

  <Tab title="go install">
    Se você tem o Go instalado:

    ```bash theme={"system"}
    go install github.com/diillson/chatcli@latest
    ```

    O binário será instalado em `$GOPATH/bin`. Garanta que está no `PATH`:

    ```bash theme={"system"}
    export PATH=$PATH:$(go env GOPATH)/bin
    ```

    Adicione a linha acima ao seu `.bashrc` ou `.zshrc` para persistir entre sessões.
  </Tab>

  <Tab title="Código-Fonte">
    Para quem quer compilar localmente ou contribuir:

    <Steps>
      <Step title="Clone o repositório">
        ```bash theme={"system"}
        git clone https://github.com/diillson/chatcli.git
        cd chatcli
        ```
      </Step>

      <Step title="Compile">
        ```bash theme={"system"}
        go mod tidy
        go build -o chatcli
        ```
      </Step>

      <Step title="(Opcional) Build com informações de versão">
        ```bash theme={"system"}
        VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo "dev")
        COMMIT_HASH=$(git rev-parse --short HEAD)
        BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

        go build -ldflags "\
          -X github.com/diillson/chatcli/version.Version=${VERSION} \
          -X github.com/diillson/chatcli/version.CommitHash=${COMMIT_HASH} \
          -X github.com/diillson/chatcli/version.BuildDate=${BUILD_DATE}" \
          -o chatcli main.go
        ```

        Isso injeta dados de versão no binário, acessíveis via `/version` ou `chatcli --version`.
      </Step>

      <Step title="Mova para o PATH">
        ```bash theme={"system"}
        sudo mv chatcli /usr/local/bin/
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Docker">
    Veja o guia completo em [Deploy com Docker e Kubernetes](/pt/start/docker-deployment).
  </Tab>
</Tabs>

***

## 2. Configurar um Provedor

Crie um arquivo `.env` na sua pasta de usuário ou na raiz do projeto.

<Tabs>
  <Tab title="OpenAI">
    ```env theme={"system"}
    LLM_PROVIDER=OPENAI
    OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

    # (Opcional) Modelo específico — padrão: gpt-6.1-sol
    # OPENAI_MODEL="gpt-6.1-sol"
    ```
  </Tab>

  <Tab title="Anthropic (Claude)">
    ```env theme={"system"}
    LLM_PROVIDER=CLAUDEAI
    ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx"

    # (Opcional) Modelo — padrão: claude-sonnet-5-5
    # ANTHROPIC_MODEL="claude-sonnet-5-5"
    ```
  </Tab>

  <Tab title="Google (Gemini)">
    ```env theme={"system"}
    LLM_PROVIDER=GOOGLEAI
    GOOGLEAI_API_KEY="AIzaxxxxxxxxxxxxxxxxxxxxxxxx"

    # (Opcional) Modelo — padrão: gemini-3.8-flash
    # GOOGLEAI_MODEL="gemini-3.8-flash"
    ```
  </Tab>

  <Tab title="xAI (Grok)">
    ```env theme={"system"}
    LLM_PROVIDER=XAI
    XAI_API_KEY="xai-xxxxxxxxxxxxxxxxxxxxxxxx"

    # (Opcional) Modelo — padrão: grok-4.3
    # XAI_MODEL="grok-4.3"
    ```
  </Tab>

  <Tab title="AWS Bedrock">
    ```env theme={"system"}
    LLM_PROVIDER=BEDROCK

    # Credenciais vêm da cadeia do AWS SDK — escolha UMA fonte:
    AWS_PROFILE="meu-profile"
    # AWS_ACCESS_KEY_ID="AKIAxxxxxxxxxxxxxxxx"
    # AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxx"

    # Região do Bedrock (fallback: AWS_REGION)
    BEDROCK_REGION="us-east-1"

    # (Opcional) Modelo padrão — aliases do catálogo funcionam
    # BEDROCK_MODEL="claude-opus-4-8"
    ```

    <Info>
      O Bedrock **não usa API key** — a autenticação é a cadeia de credenciais do AWS SDK: env vars → profiles do `~/.aws` (SSO, assume-role) → IAM role (EC2/ECS/EKS). Para SSO, VPC endpoints, overrides de schema e inference profiles, veja [AWS Bedrock](/pt/providers/bedrock).
    </Info>
  </Tab>

  <Tab title="StackSpot AI">
    ```env theme={"system"}
    LLM_PROVIDER=STACKSPOT
    CLIENT_ID="seu-client-id"
    CLIENT_KEY="seu-client-secret"

    # (Opcional) Realm/tenant — padrão: zup
    # STACKSPOT_REALM="seu-tenant-name"

    # (Opcional) Agent ID — padrão: default
    # STACKSPOT_AGENT_ID="seu-agent-id"
    ```

    <Info>
      A autenticação é feita via **OAuth 2.0 Client Credentials**. Obtenha suas credenciais no portal da [StackSpot](https://stackspot.com).
      Você também pode sobrescrever `realm` e `agent-id` via flags na linha de comando:

      ```bash theme={"system"}
      chatcli --provider STACKSPOT --realm "meu-realm" --agent-id "meu-agent" -p "Sua pergunta"
      ```
    </Info>
  </Tab>

  <Tab title="ZAI (Zhipu AI)">
    ```env theme={"system"}
    LLM_PROVIDER=ZAI
    ZAI_API_KEY="xxx"

    # (Opcional) Modelo — padrão: glm-5
    # ZAI_MODEL="glm-5"

    # (Opcional) Assinantes do GLM Coding Plan: mesma key, endpoint da assinatura
    # ZAI_USE_CODING_PLAN=true
    ```
  </Tab>

  <Tab title="MiniMax">
    ```env theme={"system"}
    LLM_PROVIDER=MINIMAX
    MINIMAX_API_KEY="xxx"

    # (Opcional) Modelo — padrão: MiniMax-M2.7 (case-sensitive!)
    # MINIMAX_MODEL="MiniMax-M2.7"
    ```
  </Tab>

  <Tab title="Moonshot (Kimi)">
    ```env theme={"system"}
    LLM_PROVIDER=MOONSHOT
    MOONSHOT_API_KEY="sk-xxx"

    # (Opcional) Modelo — padrão: kimi-k2.6
    # MOONSHOT_MODEL="kimi-k2.6"
    # MOONSHOT_THINKING="auto"   # auto | enabled | disabled
    ```
  </Tab>

  <Tab title="OpenRouter">
    ```env theme={"system"}
    LLM_PROVIDER=OPENROUTER
    OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxxxxxxxxxx"

    # (Opcional) Modelo — padrão: openai/gpt-6.1-sol
    # OPENROUTER_MODEL="anthropic/claude-sonnet-5"

    # (Opcional) Fallback nativo do OpenRouter
    # OPENROUTER_FALLBACK_MODELS="openai/gpt-4o,google/gemini-3.8-flash"
    ```

    <Info>
      O OpenRouter é um **gateway multi-provedor** que dá acesso a 200+ modelos (OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek, etc.) com uma única API key. Os modelos usam o formato `provedor/nome-do-modelo`. Obtenha sua chave em [openrouter.ai](https://openrouter.ai).
    </Info>
  </Tab>

  <Tab title="GitHub Copilot">
    ```env theme={"system"}
    LLM_PROVIDER=COPILOT
    GITHUB_COPILOT_TOKEN="ghu_xxxxxxxxxxxxxxxxxxxxxxxx"

    # (Opcional) Modelo — ex.: gpt-6.1-sol, claude-sonnet-5.5
    # COPILOT_MODEL="gpt-6.1-sol"
    ```

    <Info>
      Prefere OAuth? Dispense o token e rode `/auth login github-copilot` (Device Flow) — veja a aba **OAuth**.
    </Info>
  </Tab>

  <Tab title="Devin CLI">
    ```env theme={"system"}
    LLM_PROVIDER=DEVIN

    # (Opcional) Modelo — padrão: claude-sonnet-4.6 (slugs usam pontos)
    # DEVIN_MODEL="claude-sonnet-4.6"

    # (Opcional) Caminho explícito do binário — padrão: devin do PATH
    # DEVIN_CLI_PATH="/usr/local/bin/devin"

    # (Opcional) Valor do --respect-workspace-trust do CLI — padrão: false
    # Os turnos rodam num diretório temporário descartável sobre o qual o CLI
    # não consegue abrir o prompt de confiança, então o ChatCLI dispensa a
    # checagem. true restaura o padrão do CLI.
    # DEVIN_CLI_RESPECT_WORKSPACE_TRUST="false"
    ```

    <Info>
      Sem API key no ChatCLI — a autenticação pertence ao próprio Devin CLI (`devin auth login`). O ChatCLI usa o binário local `devin` apenas como transporte de modelo; veja [Devin Provider](/pt/providers/devin-provider).
    </Info>
  </Tab>

  <Tab title="OAuth (sem API key)">
    Se possui **ChatGPT Plus/Codex**, **Claude Pro** ou **GitHub Copilot**:

    ```bash theme={"system"}
    chatcli

    # Dentro do modo interativo:
    /auth login openai-codex     # OpenAI (PKCE OAuth)
    /auth login anthropic        # Anthropic (PKCE OAuth)
    /auth login github-copilot   # GitHub Copilot (Device Flow)
    ```

    O navegador abrirá automaticamente. Consulte a [documentação de OAuth](/pt/providers/oauth-authentication) para detalhes.
  </Tab>

  <Tab title="Ollama (Local)">
    ```env theme={"system"}
    LLM_PROVIDER=OLLAMA
    OLLAMA_ENABLED=true
    OLLAMA_BASE_URL="http://localhost:11434"
    OLLAMA_MODEL="llama3"
    ```

    <Info>
      Nenhuma API key necessária. Instale o Ollama em [ollama.com](https://ollama.com) e baixe um modelo com `ollama pull llama3`.
    </Info>
  </Tab>
</Tabs>

<Info>
  Você só precisa configurar os provedores que pretende usar. O ChatCLI detecta automaticamente quais estão disponíveis pelas chaves encontradas.
</Info>

### Variáveis de Ambiente Adicionais

| Variável | Descrição | Padrão |
| - | - | - |
| `CHATCLI_DOTENV` | Caminho explícito do arquivo de ambiente. Sem ele: `./.env` → `~/.chatcli/.env` → `~/.env`, o primeiro que existir vence (os fallbacks no home mantêm o `chatcli acp`/`mcp-server` configurados quando uma IDE os sobe sem o seu shell) | `.env` → `~/.chatcli/.env` → `~/.env` |
| `CHATCLI_LANG` | Força um idioma específico (ex: `pt-BR`, `en`) | Auto-detectado |
| `LOG_LEVEL` | Nível de log: `debug`, `info`, `warn`, `error` | `info` |
| `CHATCLI_ENV` | Modo de logging: `dev` (console colorido + arquivo), `prod` (arquivo JSON; `chatcli server`/`gateway` também logam no stderr em containers) | `prod` |
| `MAX_RETRIES` | Tentativas máximas para chamadas de API | `5` |

Para a lista completa de variáveis, consulte a [Referência de Variáveis de Ambiente](/pt/reference/environment-variables).

***

## 3. Verificar a Instalação

<Steps>
  <Step title="Verifique a versão">
    ```bash theme={"system"}
    chatcli --version
    ```
  </Step>

  <Step title="Verifique a configuração ativa">
    ```bash theme={"system"}
    chatcli
    # Dentro do modo interativo:
    /config
    ```
  </Step>

  <Step title="Faça sua primeira pergunta">
    ```bash theme={"system"}
    O que é a equação de Dirac?
    ```

    <Tip>
      Se você receber uma resposta da IA, parabéns! O ChatCLI está pronto.
    </Tip>
  </Step>
</Steps>

***

## Atualizando o ChatCLI

Depois de instalado, o ChatCLI se mantém atualizado sozinho. Rode `/update` a qualquer momento — ele detecta **como o binário foi instalado** e atualiza **pelo mesmo canal**:

```bash theme={"system"}
/update          # aplica a última release pelo seu canal de instalação
/update check    # só verifica
```

* Instalações via **Homebrew** rodam `brew upgrade diillson/chatcli/chatcli`.
* Instalações via **go install** rodam `go install github.com/diillson/chatcli@latest`.
* **Binários da release** são substituídos no lugar, verificados contra o `checksums.txt` da release.
* **Docker** e **builds locais** nunca são tocados — você recebe as instruções exatas.

Defina `CHATCLI_AUTO_UPDATE=auto` para aplicar em staging silencioso em background: o próximo start abre na versão nova. O default (`notify`) mostra o aviso na tela de boas-vindas — e na própria sessão quando uma release sai depois do boot. Veja [Auto-Update](/pt/start/auto-update) para o quadro completo.

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Uso Básico" icon="terminal" href="/pt/usage/basic-usage">
    Comandos essenciais, modos e navegação no prompt interativo.
  </Card>

  <Card title="Modo Agente" icon="robot" href="/pt/usage/agent-mode">
    Delegue tarefas para a IA executar no seu terminal.
  </Card>

  <Card title="Modo Coder" icon="code" href="/pt/usage/coder-mode">
    IA que lê, edita e testa código em loop.
  </Card>

  <Card title="Skill Registry" icon="store" href="/pt/extensions/skill-registry">
    Busque e instale skills de registries remotos.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.