CLI environment variables and file locations

This page lists every environment variable the SynapseX CLI supports and every file it reads or writes. Use it to point the CLI at a different endpoint, run it unattended in CI, or find out exactly where your credentials and session database live before you back them up or delete them.

Two commands print the authoritative values for your operating system:


synapsex-code debug paths
synapsex-code debug config

debug paths prints the resolved data, config, cache, state, log, bin, repos and tmp directories. debug config prints the merged configuration after every file below has been applied. When this page and those two commands disagree, trust the commands.

Which environment variables change where the CLI connects

Variable	What it does	Default
`SYNAPSEX_API_KEY`	API key for the built-in `synapsex` model provider. Setting it loads the provider without running `providers login`	unset
`SYNAPSEX_API_URL`	Base URL of the SynapseX model API	`https://platform.synapsex.ai/api/v1`
`SYNAPSEX_AUTH_URL`	Origin used by the device-flow sign-in for the `synapsex` provider	`https://chat.synapsex.ai`
`SYNAPSEX_COMPUTE_URL`	Origin of SynapseX Compute, used by `lab login` and the `lab` commands	`https://chat.synapsex.ai`

Setting SYNAPSEX_API_KEY is the supported way to run the CLI unattended — for example in CI, where there is no browser to complete the device flow:


export SYNAPSEX_API_KEY=YOUR_API_KEY
synapsex-code models

Which environment variables change how the CLI runs

Variable	What it does	Default
`SYNAPSEX_PYTHON`	Interpreter used by `lab run --local` for `.py` files	`python3`
`SYNAPSEX_CODE_SERVER_USERNAME`	Basic-auth username for the headless server	`synapsexCode`
`SYNAPSEX_CODE_SERVER_PASSWORD`	Basic-auth password for the headless server. Leaving it unset starts the server unsecured — `serve` and `web` say so explicitly on startup	unset
`SYNAPSEX_CODE_CONFIG`	Path to an explicit config file	unset
`SYNAPSEX_CODE_CONFIG_DIR`	Override the config directory used for global config resolution	XDG config dir
`SYNAPSEX_CODE_DISABLE_PROJECT_CONFIG`	When `true` or `1`, stop discovering per-project `.synapsexCode` directories	unset
`SYNAPSEX_CODE_LOG_LEVEL`	Same as `--log-level`	unset
`SYNAPSEX_CODE_PRINT_LOGS`	Same as `--print-logs`	unset
`SYNAPSEX_CODE_PURE`	Same as `--pure`	unset

The binary also carries a large number of experimental SYNAPSEX_CODE_* variables. They are unstable and are deliberately not documented here — do not build on them.

In which order are config files loaded?

Configuration is merged from several places. Later sources win over earlier ones, so a project setting always overrides a global one.

1. The global config directory — three files, loaded in this exact order:

Order	File
1	`config.json`
2	`synapsexCode.json`
3	`synapsexCode.jsonc`

2. Per-project config files. Starting from your current directory, the CLI walks up to the worktree root looking for synapsexCode.jsonc and synapsexCode.json. Files closer to your current directory win. Set SYNAPSEX_CODE_DISABLE_PROJECT_CONFIG=1 to switch this discovery off.

3. .synapsexCode/ directories. The same upward walk also collects .synapsexCode/ directories in the project, plus one in your home directory.

Run synapsex-code debug config to see the result of all of this on your machine.

Where does the CLI store credentials and data?

The CLI keeps its files in four standard directories, each with a synapsexCode folder inside it. Run synapsex-code debug paths to print the resolved location of each on your OS.

File	Directory	What it holds
`auth.json`	data	Your stored credentials — the `synapsex` entry created by `providers login` and the `synapsex-compute` entry created by `lab login`. Written with permissions `0600` (owner read/write only)
`synapsexCode.db`	data	The local SQLite database backing sessions and `stats`. `synapsex-code db path` prints its full path
`lab-sessions.json`	state	A map of project directory to active Lab session id, written by `lab open`. It contains only session ids — never a token
—	cache	Cache directory
`bin/`	cache	Downloaded helper binaries

To remove everything, use synapsex-code uninstall — see /reference/cli-commands for its --keep-config, --keep-data and --dry-run flags.

Installer environment variables

These are read by the install script only, not by the CLI itself.

Variable	What it does	Default
`INSTALL_DIR`	Directory the binary is written to	`/usr/local/bin` on macOS and Linux; `%LOCALAPPDATA%\synapsex-code` on Windows
`BINARY_NAME`	Name the binary is installed under	`synapsex-code`
`DOWNLOAD_BASE`	Base URL artifacts are fetched from	`https://synapsex.ai/downloads`


# Install without needing write access to /usr/local/bin
curl -fsSL https://synapsex.ai/install.sh | INSTALL_DIR=$HOME/.local/bin sh

There is no supported way to pin a version. The download URL contains no version component, so the installer always fetches the current release. To update, re-run the same install command.

Install commands and download URLs for every platform: /reference/downloads.