cli/docs/environment-variables.md

Environment Variables

The Core CLI uses environment variables for configuration, authentication, and runtime behavior. This document lists all supported environment variables and their purposes.

Configuration System

Environment variables are part of Core's layered configuration system:

1. Command-line flags (highest priority)
2. Environment variables ← This document
3. Configuration file (~/.core/config.yaml)
4. Default values (lowest priority)

Configuration File Locations

User Configuration

File	Path	Purpose
Main config	~/.core/config.yaml	User preferences and framework settings
Agentic config	~/.core/agentic.yaml	AI agent service configuration
MCP config	~/.claude/mcp_config.json	Claude Code MCP server settings
Keybindings	~/.claude/keybindings.json	Claude Code keyboard shortcuts

Project Configuration

Located in .core/ directory of project root:

File	Path	Purpose
Build config	.core/build.yaml	Build targets and flags
Release config	.core/release.yaml	Release automation settings
CI config	.core/ci.yaml	CI pipeline configuration

Registry Configuration

Searched in order:

1. Current directory: ./repos.yaml
2. Parent directories (walking up)
3. Home Code directory: ~/Code/host-uk/repos.yaml
4. Config directory: ~/.config/core/repos.yaml

General Configuration

CORE_CONFIG_*

Map configuration values to the YAML hierarchy using dot notation.

Format: CORE_CONFIG_<KEY>=<value>

After stripping the CORE_CONFIG_ prefix, the remaining variable name is converted to lowercase and underscores are replaced with dots.

Examples:

# dev.editor: vim
export CORE_CONFIG_DEV_EDITOR=vim

# log.level: debug
export CORE_CONFIG_LOG_LEVEL=debug

# ai.model: gpt-4
export CORE_CONFIG_AI_MODEL=gpt-4

NO_COLOR

Disable ANSI color output.

Values: Any value (presence disables colors)

Example:

export NO_COLOR=1
core doctor  # No colored output

CORE_DAEMON

Run application in daemon mode.

Values: 1 or true

Example:

export CORE_DAEMON=1
core mcp serve  # Runs as background daemon

MCP Server

MCP_ADDR

TCP address for MCP server. If not set, MCP uses stdio transport.

Format: host:port or :port

Default: (stdio mode)

Examples:

# Listen on localhost:9999
export MCP_ADDR=localhost:9999
core mcp serve

# Listen on all interfaces (⚠️ not recommended)
export MCP_ADDR=:9999
core mcp serve

CORE_MCP_TRANSPORT

MCP transport mode.

Values: stdio, tcp, socket

Default: stdio

Example:

export CORE_MCP_TRANSPORT=tcp
export CORE_MCP_ADDR=:9100
core daemon

CORE_MCP_ADDR

Alternative to MCP_ADDR for daemon mode.

Format: Same as MCP_ADDR

CORE_HEALTH_ADDR

Health check endpoint address for daemon mode.

Format: host:port or :port

Default: None (disabled)

Example:

export CORE_HEALTH_ADDR=:8080
core daemon
# Health check: curl http://localhost:8080/health

CORE_PID_FILE

PID file location for daemon mode.

Default: (platform-specific temp directory)

Example:

export CORE_PID_FILE=/var/run/core-mcp.pid
core daemon

Service APIs

COOLIFY_TOKEN

API token for Coolify deployments.

Example:

export COOLIFY_TOKEN=your-api-token
core deploy servers

AGENTIC_TOKEN

API token for Agentic AI services.

Example:

export AGENTIC_TOKEN=your-token
core ai tasks list

Networking

UNIFI_URL

UniFi controller URL.

Format: https://host or https://host:port

Example:

export UNIFI_URL=https://192.168.1.1
core unifi clients

UNIFI_INSECURE

Skip TLS certificate verification for UniFi controller.

Values: 1, true, yes

Example:

export UNIFI_INSECURE=1
export UNIFI_URL=https://192.168.1.1
core unifi devices

Git/Forge Integration

GITHUB_TOKEN

GitHub API token for operations requiring authentication.

Note: Usually set by GitHub CLI (gh auth login)

Example:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
core dev issues

FORGEJO_URL

Forgejo instance URL.

Example:

export FORGEJO_URL=https://forge.example.com
core forge repos

FORGEJO_TOKEN

Forgejo API token.

Example:

export FORGEJO_TOKEN=your-token
core forge issues

GITEA_URL

Gitea instance URL.

Example:

export GITEA_URL=https://gitea.example.com
core gitea repos

GITEA_TOKEN

Gitea API token.

Example:

export GITEA_TOKEN=your-token
core gitea issues

RAG System

QDRANT_HOST

Qdrant vector database host.

Default: localhost

Example:

export QDRANT_HOST=localhost
export QDRANT_PORT=6334
core rag collections list

QDRANT_PORT

Qdrant gRPC port.

Default: 6334

OLLAMA_HOST

Ollama API host for embeddings.

Default: localhost

Example:

export OLLAMA_HOST=localhost
export OLLAMA_PORT=11434
core rag ingest --collection docs --path ./documentation

OLLAMA_PORT

Ollama API port.

Default: 11434

ML Pipeline

ML_API_URL

OpenAI-compatible API endpoint for ML operations.

Example:

export ML_API_URL=http://localhost:8000/v1
core ml score

ML_JUDGE_URL

Judge model API URL (typically Ollama).

Example:

export ML_JUDGE_URL=http://localhost:11434
core ml score --judge-model llama2

ML_JUDGE_MODEL

Judge model name for scoring.

Default: (varies by command)

Example:

export ML_JUDGE_MODEL=llama2:latest
core ml score

INFLUX_URL

InfluxDB URL for metrics storage.

Example:

export INFLUX_URL=http://localhost:8086
export INFLUX_DB=metrics
core ml metrics

INFLUX_DB

InfluxDB database name.

Example:

export INFLUX_DB=ml_metrics
core ml ingest

Build System

CGO_ENABLED

Enable or disable CGO for builds.

Values: 0 (disabled), 1 (enabled)

Default: 0 (Go default)

Example:

export CGO_ENABLED=1
task cli:build

GOOS

Target operating system for cross-compilation.

Values: linux, darwin, windows, freebsd, etc.

Example:

export GOOS=linux
export GOARCH=amd64
task cli:build

GOARCH

Target architecture for cross-compilation.

Values: amd64, arm64, 386, arm, etc.

Example:

export GOOS=darwin
export GOARCH=arm64
task cli:build  # Build for Apple Silicon

Testing

TEST_VERBOSE

Enable verbose test output.

Values: 1, true

Example:

export TEST_VERBOSE=1
core test

TEST_SHORT

Run short tests only.

Values: 1, true

Example:

export TEST_SHORT=1
core test

TEST_RACE

Enable race detector.

Values: 1, true

Example:

export TEST_RACE=1
core test

Infrastructure

HETZNER_TOKEN

Hetzner Cloud API token.

Example:

export HETZNER_TOKEN=your-token
core prod status

CLOUDNS_AUTH_ID

CloudNS authentication ID for DNS management.

Example:

export CLOUDNS_AUTH_ID=your-id
export CLOUDNS_AUTH_PASSWORD=your-password
core prod dns

CLOUDNS_AUTH_PASSWORD

CloudNS authentication password.

Virtual Machines

LINUXKIT_PATH

Path to LinuxKit binary.

Default: linuxkit (from PATH)

Example:

export LINUXKIT_PATH=/usr/local/bin/linuxkit
core vm run

VM_MEMORY

Default memory allocation for VMs.

Format: Integer (MB) or string with suffix (e.g., "2G")

Default: 2048 (2GB)

Example:

export VM_MEMORY=4096
core vm run my-vm

VM_CPUS

Default CPU count for VMs.

Default: 2

Example:

export VM_CPUS=4
core vm run my-vm

Development

DEBUG

Enable debug logging.

Values: 1, true

Example:

export DEBUG=1
core dev work

LOG_LEVEL

Global log level.

Values: debug, info, warn, error

Default: info

Example:

export LOG_LEVEL=debug
core mcp serve

EDITOR

Default text editor for interactive commands.

Default: vim or system default

Example:

export EDITOR=nvim
core dev commit  # Uses neovim for editing

PAGER

Default pager for command output.

Default: less or system default

Example:

export PAGER=bat
core help

Best Practices

1. Use Config File for Persistent Settings

Environment variables are temporary. For persistent configuration, use ~/.core/config.yaml:

dev:
  editor: nvim
log:
  level: info
ai:
  model: gpt-4

Set via CLI:

core config set dev.editor nvim

2. Use .env Files for Project-Specific Settings

Create .env in project root:

# .env
MCP_ADDR=localhost:9100
QDRANT_HOST=localhost
OLLAMA_HOST=localhost

Load with:

source .env
core mcp serve

Or use direnv for automatic loading.

3. Secure Sensitive Tokens

Never commit tokens to version control:

# .gitignore
.env
.env.local
*.token

Use environment-specific files:

.env.development
.env.staging
.env.production

4. Override in CI/CD

Set environment variables in CI/CD pipelines:

# .github/workflows/test.yml
env:
  CORE_CONFIG_LOG_LEVEL: debug
  NO_COLOR: 1

5. Document Project Requirements

Create .env.example with required variables:

# .env.example
MCP_ADDR=localhost:9100
QDRANT_HOST=localhost
QDRANT_PORT=6334
OLLAMA_HOST=localhost
# FORGEJO_TOKEN=your-token-here

Checking Configuration

View Current Config

# All config values
core config list

# Specific value
core config get dev.editor

View Config File Location

core config path

Debug Environment Variables

# Show all CORE_* variables
env | grep CORE_

# Show all MCP-related variables
env | grep MCP

Test Configuration

# Verify environment setup
core doctor --verbose

Troubleshooting

Variable Not Taking Effect

1. Check priority: Command flags override environment variables

   # This flag takes priority
   core mcp serve --workspace /path
   

2. Verify variable is set:

   echo $MCP_ADDR
   

3. Check for typos:

   # Wrong
   export CORE_CONFIG_dev_editor=vim
   
   # Correct
   export CORE_CONFIG_DEV_EDITOR=vim
   

4. Restart shell or reload:

   source ~/.bashrc  # or ~/.zshrc
   

Config File vs Environment Variables

If config file and environment variable conflict, environment variable wins:

# ~/.core/config.yaml
log:
  level: info

# This overrides the config file
export CORE_CONFIG_LOG_LEVEL=debug
core mcp serve  # Uses debug level

Case Sensitivity

Variable names are case-sensitive:

# Wrong
export mcp_addr=:9100

# Correct
export MCP_ADDR=:9100

See Also

• Configuration Reference - Complete config file documentation
• CLI Reference - Command documentation
• MCP Integration - MCP server setup
• Getting Started - Installation and setup