> ## 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.26+" 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/getting-started/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-5.4
    # OPENAI_MODEL="gpt-5.4"
    ```
  </Tab>

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

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

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

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

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

    # (Opcional) Modelo — padrão: grok-4-1
    # XAI_MODEL="grok-4-1"
    ```
  </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"
    ```
  </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-4o
    # MODEL="anthropic/claude-sonnet-4"

    # (Opcional) Fallback nativo do OpenRouter
    # OPENROUTER_FALLBACK_MODELS="openai/gpt-4o,google/gemini-2.5-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="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/features/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 customizado para o arquivo `.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` (só arquivo JSON) | `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>

***

## Próximos Passos

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

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

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

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