Installation and Configuration

Prerequisites

Git

Required to clone the repository and for Go to download dependencies.

Go 1.26+

Only needed for go install or building from source.

API Key or OAuth

An API key from an LLM provider or an account with an active plan for OAuth.

1. Installation

Homebrew (Recommended)
Binary
go install
From Source
Docker

The easiest way for macOS and Linux. Installs and updates automatically.

brew tap diillson/chatcli
brew install chatcli

To upgrade:

brew upgrade chatcli

Supports macOS (Apple Silicon and Intel) and Linux (amd64). The formula is automatically updated on each release.

Download the binary for your system directly from the Releases page.

# Linux/macOS — adjust the filename according to the release
chmod +x chatcli
sudo mv chatcli /usr/local/bin/

Available for Linux, macOS, and Windows on amd64 and arm64 architectures.

If you have Go installed:

go install github.com/diillson/chatcli@latest

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

export PATH=$PATH:$(go env GOPATH)/bin

Add the line above to your .bashrc or .zshrc to persist across sessions.

For those who want to compile locally or contribute:

Clone the repository

git clone https://github.com/diillson/chatcli.git
cd chatcli

Build

go mod tidy
go build -o chatcli

(Optional) Build with version information

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.

Move to PATH

sudo mv chatcli /usr/local/bin/

2. Configure a Provider

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

LLM_PROVIDER=OPENAI
OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# (Optional) Specific model — default: gpt-5.4
# OPENAI_MODEL="gpt-5.4"

LLM_PROVIDER=CLAUDEAI
ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx"

# (Optional) Model — default: claude-sonnet-4-6
# ANTHROPIC_MODEL="claude-sonnet-4-6"

LLM_PROVIDER=GOOGLEAI
GOOGLEAI_API_KEY="AIzaxxxxxxxxxxxxxxxxxxxxxxxx"

# (Optional) Model — default: gemini-2.5-flash
# GOOGLEAI_MODEL="gemini-2.5-pro"

LLM_PROVIDER=XAI
XAI_API_KEY="xai-xxxxxxxxxxxxxxxxxxxxxxxx"

# (Optional) Model — default: grok-4-1
# XAI_MODEL="grok-4-1"

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"

Authentication uses OAuth 2.0 Client Credentials. Get your credentials from the StackSpot portal. You can also override realm and agent-id via command-line flags:

chatcli --provider STACKSPOT --realm "my-realm" --agent-id "my-agent" -p "Your prompt"

LLM_PROVIDER=ZAI
ZAI_API_KEY="your-zai-api-key"

# (Optional) Model — default: glm-5
# ZAI_MODEL="glm-4.7"

LLM_PROVIDER=MINIMAX
MINIMAX_API_KEY="your-minimax-api-key"

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

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

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"

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.

If you have ChatGPT Plus/Codex, Claude Pro, or GitHub Copilot:

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 for details.

LLM_PROVIDER=OLLAMA
OLLAMA_ENABLED=true
OLLAMA_BASE_URL="http://localhost:11434"
OLLAMA_MODEL="llama3"

No API key required. Install Ollama from ollama.com and download a model with ollama pull llama3.

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

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.

3. Verify the Installation

Check the version

chatcli --version

Check the active configuration

chatcli
# Inside interactive mode:
/config

Ask your first question

What is the Dirac equation?

If you get a response from the AI, congratulations! ChatCLI is ready to use.

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:

/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 for the full picture.

Next Steps

Basic Usage

Essential commands, modes, and navigation in the interactive prompt.

Agent Mode

Delegate tasks for the AI to execute in your terminal.

Coder Mode

AI that reads, edits, and tests code in a loop.

Skill Registry

Search and install skills from remote registries.

Home

Getting Started

Core Concepts

Features

Security

Support

Installation and Configuration

Prerequisites

Git

Go 1.26+

API Key or OAuth

1. Installation

2. Configure a Provider

Additional Environment Variables

3. Verify the Installation

Updating ChatCLI

Next Steps

Basic Usage

Agent Mode

Coder Mode

Skill Registry

​Prerequisites

Git

Go 1.26+

API Key or OAuth

​1. Installation

​2. Configure a Provider

​Additional Environment Variables

​3. Verify the Installation

​Updating ChatCLI

​Next Steps

Basic Usage

Agent Mode

Coder Mode

Skill Registry

Prerequisites

1. Installation

2. Configure a Provider

Additional Environment Variables

3. Verify the Installation

Updating ChatCLI

Next Steps