ncode CLI / Get started

Quickstart

This page takes you from a fresh install to a first finished task in a few minutes. You need ncode installed and a key for a model provider: Anthropic, OpenAI, OpenRouter, DeepSeek, or any other OpenAI-compatible endpoint. A local server such as Ollama or LM Studio works without a key.

Add a model provider#

ncode ships with no key of its own. Until you add a provider that can answer, a session does not start and says:

No model provider is set up yet.
Run 'ncode settings providers' to add one, or set NCODE_MODEL, NCODE_BASE_URL and NCODE_API_KEY in ~/.secrets (the older SWARM_* names still work).

There are two ways to add one.

In Settings#

ncode settings providers

This opens the settings screen at Providers, even with no provider set up.

1. Add a provider and pick a preset: Anthropic, OpenAI, OpenRouter, DeepSeek, Ollama, LM Studio, or Other for any OpenAI-compatible endpoint. The preset fills in the kind and the base URL.
2. Paste your key. It is never shown: the row reads ●●●●●●●● set · ends 4f2a.
3. Press Ctrl+S. ncode creates the provider, stores the key and tests the connection. A failed test shows on the provider's row; fix the key and test again.
4. Fetch the model list and pick the model you want to chat with.

The same from a shell, for example with Anthropic (the key is read from stdin, so it never lands in your shell history):

ncode config record add provider --preset anthropic
printf '%s' "$ANTHROPIC_API_KEY" | ncode config secret provider:Anthropic --stdin
ncode config set models.chat Anthropic/<model-id>

From the environment (first run only)#

If the database has no usable provider yet, the first launch can create one from environment variables and says that it did. Two of them are required, the model and the endpoint; the kind defaults to openai, and the key may be empty for a local server.

NCODE_PROVIDER=anthropic \
NCODE_MODEL=<model-id> \
NCODE_BASE_URL=https://api.anthropic.com \
NCODE_API_KEY="$ANTHROPIC_API_KEY" \
ncode

• NCODE_PROVIDER is anthropic or openai (the default, for any OpenAI-compatible endpoint).
• OpenAI-compatible URLs end in /v1 (https://api.openai.com/v1); Anthropic URLs do not.
• A local server may use an empty key: NCODE_API_KEY=.
• Setting only a key does nothing: without a model and an endpoint no provider is created.

Instead of exporting them, you can put the same lines in ~/.secrets (one NAME=value per line): ncode reads that file when no key is exported. After the first run these variables are ignored: the providers in Settings decide. The older SWARM_… names are still read. See Environment variables.

Open a project#

cd ~/dev/app
ncode

ncode opens the folder you run it from (or the one you name, ncode ~/dev/app) as the project, in full screen, with the composer ready for typing. It continues the project's latest conversation; ncode --new starts a fresh one.

Trust the project#

A project you open for the first time is read-only: agents can read and search, but not write files or run commands, and the project's AGENTS.md is not read. The mode is always on the status line.

When you trust the code in the folder, type:

/trust

The project moves to auto, and the chat says Approvals: read-only → auto. In auto, file edits and safe commands such as ls or git status run by themselves; other commands ask you first. Approvals and trust explains the modes.

Ask something#

Type a request and press Enter:

Add a --verbose flag to the CLI parser and a test for it.

The answer streams into the transcript. Each file the assistant reads or edits and each command it runs is one row you can open with Enter in select mode (Ctrl+T). Esc stops the turn at any time; your draft stays.

Approve a command#

When the assistant wants to run a command that auto mode does not allow on its own, a card opens above the composer with the command. Answer with one letter:

The letters answer only while your draft is empty, so a sentence you are typing never answers a card by accident.

Quit and come back#

Press Ctrl+C twice within a second and a half. If runs are still working, ncode asks first. After the full screen closes, a short summary lists the runs it stopped and how to reopen the conversation:

ncode --resume <conversation-id>

Plain ncode in the same folder also reopens the latest conversation. Next: the session screen and the composer.