> ## 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.

# Installation and Configuration

> Learn how to install ChatCLI and configure your API keys to get started.

## Prerequisites

<CardGroup cols={3}>
  <Card title="Git" icon="code-branch">
    Required to clone the repository and for Go to download dependencies.
  </Card>

  <Card title="Go 1.26+" icon="golang">
    Only needed for `go install` or building from source.
  </Card>

  <Card title="API Key or OAuth" icon="key">
    An API key from an LLM provider **or** an account with an active plan for OAuth.
  </Card>
</CardGroup>

***

## 1. Installation

<Tabs>
  <Tab title="Homebrew (Recommended)">
    The easiest way for **macOS** and **Linux**. Installs and updates automatically.

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

    To upgrade:

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

    <Tip>
      Supports **macOS** (Apple Silicon and Intel) and **Linux** (amd64). The formula is automatically updated on each release.
    </Tip>
  </Tab>

  <Tab title="Binary">
    Download the binary for your system directly from the [Releases page](https://github.com/diillson/chatcli/releases).

    ```bash theme={"system"}
    # Linux/macOS — adjust the filename according to the release
    chmod +x chatcli
    sudo mv chatcli /usr/local/bin/
    ```

    <Tip>
      Available for **Linux**, **macOS**, and **Windows** on **amd64** and **arm64** architectures.
    </Tip>
  </Tab>

  <Tab title="go install">
    If you have Go installed:

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

    The binary will be installed in `$GOPATH/bin`. Make sure it is in your `PATH`:

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

    Add the line above to your `.bashrc` or `.zshrc` to persist across sessions.
  </Tab>

  <Tab title="From Source">
    For those who want to compile locally or contribute:

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

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

      <Step title="(Optional) Build with version information">
        ```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
        ```

        This injects version data into the binary, accessible via `/version` or `chatcli --version`.
      </Step>

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

  <Tab title="Docker">
    See the full guide at [Deploy with Docker and Kubernetes](/getting-started/docker-deployment).
  </Tab>
</Tabs>

***

## 2. Configure a Provider

Create a `.env` file in your home directory or in the project root.

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

    # (Optional) Specific model — default: 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"

    # (Optional) Model — default: 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"

    # (Optional) Model — default: gemini-2.5-flash
    # GOOGLEAI_MODEL="gemini-2.5-pro"
    ```
  </Tab>

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

    # (Optional) Model — default: grok-4-1
    # XAI_MODEL="grok-4-1"
    ```
  </Tab>

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

    # (Optional) Realm/tenant — default: zup
    # STACKSPOT_REALM="your-tenant-name"

    # (Optional) Agent ID — default: default
    # STACKSPOT_AGENT_ID="your-agent-id"
    ```

    <Info>
      Authentication uses **OAuth 2.0 Client Credentials**. Get your credentials from the [StackSpot](https://stackspot.com) portal.
      You can also override `realm` and `agent-id` via command-line flags:

      ```bash theme={"system"}
      chatcli --provider STACKSPOT --realm "my-realm" --agent-id "my-agent" -p "Your prompt"
      ```
    </Info>
  </Tab>

  <Tab title="ZAI (Zhipu AI)">
    ```env theme={"system"}
    LLM_PROVIDER=ZAI
    ZAI_API_KEY="your-zai-api-key"

    # (Optional) Model — default: glm-5
    # ZAI_MODEL="glm-4.7"
    ```
  </Tab>

  <Tab title="MiniMax">
    ```env theme={"system"}
    LLM_PROVIDER=MINIMAX
    MINIMAX_API_KEY="your-minimax-api-key"

    # (Optional) Model — default: MiniMax-M2.7 (case-sensitive!)
    # MINIMAX_MODEL="MiniMax-M2.5"
    ```
  </Tab>

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

    # (Optional) Model — default: 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"

    # (Optional) Model — default: openai/gpt-4o
    # MODEL="anthropic/claude-sonnet-4"

    # (Optional) Server-side fallback routing
    # OPENROUTER_FALLBACK_MODELS="anthropic/claude-sonnet-4,google/gemini-2.5-flash"
    ```

    <Info>
      OpenRouter is a **multi-provider gateway** — one API key gives access to 200+ models from OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek, and more. Get your key at [openrouter.ai](https://openrouter.ai).
    </Info>
  </Tab>

  <Tab title="OAuth (no API key)">
    If you have **ChatGPT Plus/Codex**, **Claude Pro**, or **GitHub Copilot**:

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

    # Inside interactive mode:
    /auth login openai-codex     # OpenAI (PKCE OAuth)
    /auth login anthropic        # Anthropic (PKCE OAuth)
    /auth login github-copilot   # GitHub Copilot (Device Flow)
    ```

    The browser will open automatically. See the [OAuth documentation](/features/oauth-authentication) for details.
  </Tab>

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

    <Info>
      No API key required. Install Ollama from [ollama.com](https://ollama.com) and download a model with `ollama pull llama3`.
    </Info>
  </Tab>
</Tabs>

<Info>
  You only need to configure the providers you plan to use. ChatCLI automatically detects which ones are available based on the keys found.
</Info>

### Additional Environment Variables

| Variable         | Description                                                           | Default       |
| ---------------- | --------------------------------------------------------------------- | ------------- |
| `CHATCLI_DOTENV` | Custom path for the `.env` file                                       | `.env`        |
| `CHATCLI_LANG`   | Force a specific language (e.g., `pt-BR`, `en`)                       | Auto-detected |
| `LOG_LEVEL`      | Log level: `debug`, `info`, `warn`, `error`                           | `info`        |
| `CHATCLI_ENV`    | Logging mode: `dev` (colored console + file), `prod` (file-only JSON) | `prod`        |
| `MAX_RETRIES`    | Maximum retries for API calls                                         | `5`           |

For the complete list of variables, see the [Environment Variables Reference](/reference/environment-variables).

***

## 3. Verify the Installation

<Steps>
  <Step title="Check the version">
    ```bash theme={"system"}
    chatcli --version
    ```
  </Step>

  <Step title="Check the active configuration">
    ```bash theme={"system"}
    chatcli
    # Inside interactive mode:
    /config
    ```
  </Step>

  <Step title="Ask your first question">
    ```bash theme={"system"}
    What is the Dirac equation?
    ```

    <Tip>
      If you get a response from the AI, congratulations! ChatCLI is ready to use.
    </Tip>
  </Step>
</Steps>

***

## Updating ChatCLI

Once installed, ChatCLI keeps itself current. Run `/update` at any time — it detects **how the binary was installed** and updates **through that same channel**:

```bash theme={"system"}
/update          # apply the latest release via your install channel
/update check    # only check
```

* **Homebrew** installs run `brew upgrade diillson/chatcli/chatcli`.
* **go install** installs run `go install github.com/diillson/chatcli@latest`.
* **Release binaries** are self-replaced in place, verified against the release's `checksums.txt`.
* **Docker** and **source builds** are never touched — you get the exact instructions instead.

Set `CHATCLI_AUTO_UPDATE=auto` to stage updates silently in the background: the next start opens on the new version. The default (`notify`) shows an update hint on the welcome screen — and in the running session when a release lands after boot. See [Auto-Update](/features/auto-update) for the full picture.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Basic Usage" icon="terminal" href="/core-concepts/basic-usage">
    Essential commands, modes, and navigation in the interactive prompt.
  </Card>

  <Card title="Agent Mode" icon="robot" href="/core-concepts/agent-mode">
    Delegate tasks for the AI to execute in your terminal.
  </Card>

  <Card title="Coder Mode" icon="code" href="/core-concepts/coder-mode">
    AI that reads, edits, and tests code in a loop.
  </Card>

  <Card title="Skill Registry" icon="store" href="/features/skill-registry">
    Search and install skills from remote registries.
  </Card>
</CardGroup>