Environment Variables

All environment variables recognized by the OneCLI gateway, CLI, and Docker image. Proxy config, auth, logging, and feature flags.

Server configuration

All environment variables are optional for local development. The defaults provide a working setup out of the box.

Variable	Default	Description
DATABASE_URL	Bundled PostgreSQL	PostgreSQL connection string. The Docker Compose setup includes PostgreSQL by default.
SECRET_ENCRYPTION_KEY	Auto-generated	AES-256-GCM encryption key for the secret store. Auto-generated on first run if not set.
NEXTAUTH_SECRET	-	Enables Google OAuth (multi-user mode). Without this, OneCLI runs in single-user mode with no login required.
GOOGLE_CLIENT_ID	-	Google OAuth client ID. Required if NEXTAUTH_SECRET is set.
GOOGLE_CLIENT_SECRET	-	Google OAuth client secret. Required if NEXTAUTH_SECRET is set.

Single-user vs multi-user mode

By default, OneCLI runs in single-user mode with no login screen. This is ideal for local development and personal use.

To enable multi-user mode with Google OAuth, set the three auth variables:

NEXTAUTH_SECRET=your-random-secret
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Bring your own database

By default, the Docker Compose setup bundles a PostgreSQL instance. To use an external PostgreSQL instance instead:

DATABASE_URL=postgresql://user:password@host:5432/onecli

Telemetry

Variable	Default	Description
DO_NOT_TRACK	-	Set to 1 to disable anonymous telemetry. Supported by many open-source tools (Next.js, Homebrew, Gatsby, Sanity, Railway, etc.).

See Telemetry for details on what is collected and how to opt out.

CLI configuration variables

These variables configure the onecli CLI tool. Each one overrides the matching stored value, so they suit CI jobs and scripts where writing config files is awkward.

Variable	Default	Description
ONECLI_API_KEY	-	API key. Overrides the key stored by onecli auth login.
ONECLI_API_HOST	https://api.onecli.sh	API base URL. Overrides onecli config set api-host.
ONECLI_PROJECT	-	Active project slug. Overrides onecli config set project.
ONECLI_AGENT	-	Agent identifier for onecli run. Overrides onecli config set agent.
ONECLI_ENV	production	Set to dev for development mode

Development vs production

Setting ONECLI_ENV=dev switches the CLI to development mode, which uses separate files and keychain entries so it never interferes with your production setup:

Path / Key	Production	Development
Credentials directory	~/.onecli/credentials	~/.onecli/credentials-dev
Config file	~/.onecli/config.json	~/.onecli/config-dev.json
Keychain service name	onecli-api-key	onecli-api-key-dev

Variables set by onecli run

onecli run injects these into the wrapped agent process. They are not user-configurable:

Variable	Description
HTTPS_PROXY, HTTP_PROXY	Route the agent’s traffic through the gateway, carrying the agent’s access token
SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO, DENO_CERT	Trust the gateway CA (all point at ~/.onecli/ca-bundle.pem)
ONECLI_GATEWAY	Set to true so agents and scripts can detect they run behind the gateway
ONECLI_GATEWAY_SKILL_PATH	Path to the gateway skill file, set for commands without a dedicated integration

See the Coding Agents guide for what onecli run does end to end.