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 is given and an endpoint is known; a missing model or endpoint stops the launch with a sentence that says which (NCODE_MODEL is missing., NCODE_BASE_URL is missing (OpenAI-compatible URLs end in /v1).). 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; with only ANTHROPIC_API_KEY or OPENAI_API_KEY set, the endpoint defaults to https://api.anthropic.com or https://api.openai.com/v1 |
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), and for this session's chat model while the conversation has no level of its own: the status line shows it and the /effort list and picker mark it. An /effort you set wins for the conversation; /effort default gives it back |
Where they are loaded from#
ncode uses what you exported in your shell. 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. The file is read one variable at a time: a variable you exported (even an empty one) always wins, and the others are filled from the file. A named NCODE_ENV_FILE that does not exist stops the launch with exit code 2.
| 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 | 1 sends mouse and wheel reports to ncode (off by default; the wheel still scrolls through the terminal), 0 keeps them off | /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.