ncode CLI / Automation

ncode config

ncode config does what the settings screen does, from a shell: it goes through the same service and the same checks, so a value it accepts is one the screen would accept. ncode config help lists every command.

ncode config list --modified
ncode config set limits.max_agent_depth 3
ncode config record add provider --preset deepseek
printf '%s' "$DEEPSEEK_KEY" | ncode config secret provider:DeepSeek --stdin
ncode config set models.chat DeepSeek/<model-id>
ncode config search order tavily,exa

Every key is listed in the settings reference.

Reading#

Changing#

ncode config set KEY VALUE [--project DIR] [--conversation ID|latest] [--expect VALUE]
ncode config reset KEY [--project DIR] [--conversation ID|latest]

Values are typed as in Settings: on/off, durations such as 30m or 90s, default, null, lists as a,b,c, models as provider/model, colours as #RRGGBB.

• --project DIR changes a project setting for that project (by default, the current folder's).
• --conversation ID (or latest) changes a setting of one conversation.
• --expect VALUE changes the value only if it still is VALUE; otherwise the command exits with code 4, "changed elsewhere". Use it when two scripts or a person may change the same setting.

reset puts a setting back to its default.

Records: providers, search engines and MCP servers#

Providers, search engines and MCP servers are records with fields of their own. KIND is provider, search_provider or mcp_server.

ncode config records provider
ncode config record get provider:Anthropic
ncode config record set provider:Anthropic.base_url https://api.anthropic.com
ncode config record add provider --preset anthropic [--name "Work Anthropic"]
ncode config record add mcp_server docs --http https://mcp.example.com/mcp
ncode config record add mcp_server files --stdio npx -y @modelcontextprotocol/server-filesystem .
ncode config record delete provider:Anthropic --yes

Provider presets are anthropic, openai, openrouter, deepseek, ollama, lmstudio and other (see Providers and models).

Secrets#

Keys are read from standard input only, so they never land in your shell history or the process list. Naming a key as a setting, as in ncode config set provider:Anthropic.api_key … or an MCP server's env. or headers. slot, is refused with exit code 2 and a sentence that points you to ncode config secret … --stdin.

printf '%s' "$ANTHROPIC_API_KEY" | ncode config secret provider:Anthropic --stdin
printf '%s' "$TAVILY_KEY" | ncode config secret search_provider:tavily --stdin
printf '%s' "$GITHUB_TOKEN" | ncode config secret mcp_server:github.env.GITHUB_PERSONAL_ACCESS_TOKEN --stdin
printf '%s' "$TOKEN" | ncode config secret mcp_server:docs.headers.Authorization --stdin

Run in a terminal without a pipe, secret … --stdin asks you to paste the key and does not echo it. A provider key is tested against the endpoint before it is saved; --no-test skips the test.

Search engines#

ncode config search enable tavily
ncode config search disable brave
ncode config search order tavily,exa,brave

Engines are tried in this order; see Web search.

MCP servers#

ncode config mcp toggle docs
ncode config mcp reconnect docs

Export and import#

ncode config export settings.json
ncode config import settings.json            # changes nothing yet
ncode config import settings.json --apply    # imports it

export writes your settings to a file you can keep in dotfiles or move to another Mac. --no-terminal leaves out this terminal's own settings, --no-project the project's, --include-records adds providers, search engines and MCP servers. Keys are never exported.

Doctor#

ncode config doctor

checks the files and the environment ncode relies on (the same checks as Settings → Files & environment); --json for scripts.

While a session is open#

While a ncode session is open, settings kept in the shared database can be changed only from that session: config set on one of them exits with code 3 and names the process that holds the database. This terminal's own settings (theme, panel, mouse and the other terminal.* keys, kept in cli.json) can always be set.

While the desktop app is open, ncode config refuses with code 3 like every other ncode command; see Works with the desktop app.

Exit codes#