ncode CLI Configure
Environment variables
Most of ncode is set up in Settings. Environment variables are for the first run on a new Mac, for a single launch, and for scripts.
Note Every NCODE_… variable below also works under its older name with SWARM_ in front (SWARM_MODEL, SWARM_THEME, …). When both are set, the NCODE_ one wins.
Provider (first run only)#
These create a provider only when the database has no usable provider yet, and only when a model and an endpoint are given; a key alone does nothing. Afterwards they are ignored: the providers in Settings decide, and environment variables never add providers or change a conversation's model. See the Quickstart.
| Variable | Meaning |
|---|---|
NCODE_PROVIDER | openai (the default, for any OpenAI-compatible endpoint) or anthropic |
NCODE_MODEL | the model id; OPENAI_MODEL or ANTHROPIC_MODEL also work |
NCODE_BASE_URL | the endpoint; OpenAI-compatible URLs end in /v1, Anthropic URLs do not. OPENAI_BASE_URL or ANTHROPIC_BASE_URL also work |
NCODE_API_KEY | the key; wins over OPENAI_API_KEY or ANTHROPIC_API_KEY. May be empty for a local server |
NCODE_EFFORT | the reasoning effort for that first setup (medium if unset) |
Where they are loaded from#
ncode uses what you exported in your shell. When no provider key is exported, it also reads ~/.secrets, or the file named by NCODE_ENV_FILE, but only provider variables, such as NCODE_…, SWARM_…, OPENAI_… and ANTHROPIC_…; a GitHub, npm or other token in the same file never reaches ncode. An exported key, even an empty one, skips the file.
| Variable | Meaning |
|---|---|
NCODE_ENV_FILE | the shell file to read instead of ~/.secrets |
Session#
| Variable | Meaning | Wins over |
|---|---|---|
NCODE_CONVERSATION | latest (default), new, or a conversation id | Settings → Session & startup; the flags --new, --continue and --resume win over it |
NCODE_THEME | dark or light | /theme and the desktop app's mode |
NCODE_MOUSE | 0 turns wheel scrolling off, 1 on | /mouse |
NCODE_KEYMAP | vim for vim keys in the composer | Settings → Keys & input |
NCODE_ASCII | 1 draws plain ASCII glyphs | Settings → Appearance |
NCODE_SHELL | the shell agents' commands run in | Settings → Agents & limits → Shell |
The older name of NCODE_SHELL is SWARM_CODE_SHELL.
Standard variables#
| Variable | Meaning |
|---|---|
NO_COLOR | a monochrome screen |
VISUAL, EDITOR | the editor Ctrl+X opens (else vi) |
TERM, COLORTERM | which glyph set the terminal gets (see Terminal, themes and mouse) |
Not used by ncode#
SWARM_PROJECT_ROOT is ignored: ncode opens the directory you name, or the one you run it from, so a value left in ~/.secrets does not open one project from everywhere.