env.example

# AiNxt CLI — environment reference
#
# Copy to .env, edit, then source it:
#
#   cp env.example .env
#   set -a && . ./.env && set +a
#
# .env is gitignored. Nothing here is required to *build* the binary — these are
# all runtime settings. Every value below is a documented default taken from the
# source, not a guess; where a default is empty, the open-source build genuinely
# ships it empty.
#
# This file covers the settings needed to operate the CLI. It is not the whole
# environment surface: the code reads ~350 AINXT_* variables, most of them
# internal test or tuning knobs. The fullest prose reference is
# crates/codegen/ainxt-pager/docs/user-guide/05-configuration.md.

# =============================================================================
# 1. Gateway — start here
# =============================================================================
# The CLI ships with NO bundled models and NO default gateway. It reads its
# model catalogue from a gateway you operate.
#
# IMPORTANT — how this URL is used. The CLI appends `/ainxt/v1/api` to whatever
# you set here, then calls:
#     GET  {AINXT_GATEWAY_URL}/ainxt/v1/api/models
#     POST {AINXT_GATEWAY_URL}/ainxt/v1/api/messages
# The suffix is added only if not already present, so both
# `https://gw.example.com` and `https://gw.example.com/ainxt/v1/api` work.
#
# This means AINXT_GATEWAY_URL is for an AiNxt Platform gateway (ainxt-enterprise)
# or another server that serves those two paths. Pointing it directly at Ollama,
# vLLM or a plain OpenAI-compatible server will NOT work — those serve `/v1/...`,
# not `/ainxt/v1/api/...`, and you will get 404s and an empty model list.
# To use a local or OpenAI-compatible model instead, skip this variable and see
# section 6 below.
#
# Default when unset: http://localhost:8000/ainxt/v1/api
AINXT_GATEWAY_URL=http://localhost:8000

# Allow a plaintext http:// gateway on a NON-loopback host. Loopback
# (localhost / 127.0.0.1) is always allowed without this. Dev/SIT only.
#AINXT_ALLOW_INSECURE=1

# =============================================================================
# 2. Authentication — pick ONE
# =============================================================================
# Credential resolution order, highest first:
#   model `api_key` > model `env_key` > AINXT_DEPLOYMENT_KEY > AINXT_TOKEN
#   > token saved by `ainxt login` (~/.ainxt/credentials.json) > AINXT_API_KEY
#
# Interactive: run `ainxt login` and paste a bearer token. For headless/CI, set
# one of these instead and skip login entirely.

# Bearer token for non-interactive / CI use.
#AINXT_TOKEN=

# Enterprise deployment key. Takes priority over AINXT_TOKEN.
#AINXT_DEPLOYMENT_KEY=

# Global API-key fallback. This is the variable to set when you are NOT using a
# gateway at all — e.g. driving a local Ollama model via config.toml (section 6).
# The CLI refuses to start a session with no credential of any kind, even when
# the endpoint itself needs none, so a placeholder is required in that case.
# (Legacy alias also accepted by the code: AINXT_CODE_AINXT_API_KEY)
#AINXT_API_KEY=

# =============================================================================
# 3. Headless / CI  — read this before scripting the CLI
# =============================================================================
# Retry budget for API calls. Default is 15 retries with exponential backoff
# capped at 30s, which is about 6 MINUTES of retrying.
#
# These retries produce NO output while they run. An empty model catalogue --
# the usual cause of an apparent hang -- is now caught before the prompt is sent
# and fails in seconds with an explanation. But if the catalogue loads and the
# request then fails, the full budget is still spent in silence. Set this low in
# CI so those failures surface fast too:
#AINXT_MAX_RETRIES=2

# Per-request connect timeout, seconds.
#AINXT_CONNECT_TIMEOUT_SECS=

# =============================================================================
# 4. Config / state location
# =============================================================================
# Directory for config.toml, credentials.json, sessions and caches.
# Default: ~/.ainxt
#AINXT_HOME=

# =============================================================================
# 5. Wire protocol
# =============================================================================
# Force the request format for all models: messages | chat_completions | responses
# Leave unset unless your gateway requires a specific one; per-model config
# (`api_backend` in config.toml) is the finer-grained control.
#AINXT_API_BACKEND=

# =============================================================================
# 6. Calling a provider directly, with your own key (no AiNxt gateway)
# =============================================================================
# Works for ANY provider with an HTTP API -- cloud or local: Anthropic, OpenAI,
# Together AI, Ollama, vLLM, LiteLLM, llama.cpp. No accounts, no `ainxt login`.
#
# Do NOT use AINXT_GATEWAY_URL for this (see section 1). Two options:
#
# (a) Per-model entry in $AINXT_HOME/config.toml — recommended:
#
#       [model.ollama-llama]
#       model = "llama3.1:latest"
#       base_url = "http://localhost:11434/v1"
#       name = "Llama 3.1 (Ollama)"
#
#     then: export AINXT_API_KEY=local   # placeholder; Ollama ignores it
#           ainxt -m ollama-llama -p "hello"
#
#     A cloud provider is the same mechanism; only base_url, the auth field and
#     api_backend change. Anthropic uses the Messages protocol + x-api-key:
#
#       [model.claude-opus]
#       model = "claude-opus-4-6"
#       base_url = "https://api.anthropic.com/v1"
#       api_backend = "messages"
#       extra_headers = { "x-api-key" = "sk-ant-...", "anthropic-version" = "2023-06-01" }
#
#     Wire protocols: messages | chat_completions (default) | responses
#     Worked examples for every provider:
#     crates/codegen/ainxt-pager/docs/user-guide/11-custom-models.md
#
# (b) Point the whole model API elsewhere with these overrides:

# Override the model API base independently of the gateway.
#AINXT_API_BASE_URL=http://localhost:11434/v1

# Override just the catalogue source. Setting this switches the CLI to API-key
# auth (Authorization: Bearer) instead of session auth — no `ainxt login` needed.
#AINXT_MODELS_BASE_URL=
# Full URL of the model-list endpoint, if it is not {base}/models.
#AINXT_MODELS_LIST_URL=

# Model used when none is given on the command line.
#AINXT_DEFAULT_MODEL=

# =============================================================================
# 7. Auto-update
# =============================================================================
# Update channel: gateway | gh-release | internal | npm
# Auto-detected from AINXT_GATEWAY_URL when unset.
#AINXT_INSTALLER=

# Disable the background update check entirely.
#AINXT_DISABLE_AUTOUPDATER=1

# =============================================================================
# 8. Plugin marketplace
# =============================================================================
# Default: https://github.com/ainxt-org/plugin-marketplace.git
# Override to point at a registry you operate.
#AINXT_MARKETPLACE_SOURCE_URL=
# Owner/repo slug used for canonical matching. Default: ainxt-org/plugin-marketplace
#AINXT_MARKETPLACE_ORG=

# =============================================================================
# 9. UI / branding links
# =============================================================================
# ALL of these ship EMPTY in the open-source build, on purpose: they previously
# pointed at a domain the project did not own (see the note in
# crates/codegen/ainxt-env/src/lib.rs). Empty means "this build has no such
# page" and the UI omits the link rather than offering a dead one. Set them only
# to pages you control.
#AINXT_URL_SUBSCRIBE=
#AINXT_URL_USAGE=
#AINXT_URL_DOCS=
#AINXT_URL_LEGAL=
#AINXT_URL_PROMO=
#AINXT_URL_CONNECTORS=
#AINXT_URL_CHANGELOG_BASE=

# =============================================================================
# 10. Telemetry
# =============================================================================
# Off unless explicitly enabled. No endpoint is compiled in.
#AINXT_TELEMETRY_ENABLED=0

# =============================================================================
# 11. Sandbox / permissions
# =============================================================================
# See crates/codegen/ainxt-pager/docs/user-guide/18-sandbox.md and
# 22-permissions-and-safety.md before relaxing anything here.
#AINXT_SANDBOX=
#AINXT_SANDBOX_PROFILE=

# =============================================================================
# 12. Debugging
# =============================================================================
# Enable debug logging: 1, or a file path.
#AINXT_DEBUG_LOG=1

# Tracing filter. The CLI logs the model-fetch URL, the selected model and any
# auth/stream errors here — this is the first thing to turn on when the CLI
# appears to do nothing.
#RUST_LOG=ainxt_shell=debug,ainxt_sampler=debug