ncode CLI Help
Works with the desktop app
The ncode command and the ncode desktop app are two ways into the same work. If you use both on one Mac, this page is the one to read.
One machine, one database#
The desktop app and the ncode command on the same Mac use the same database, ~/Library/Application Support/SwarmCode/swarm_code.db. Your projects, conversations, settings, keys and schedules are the same in both: a conversation started in one can be continued in the other.
Only one of them may have the database open at a time. Three rules keep it safe:
- Quit the app before you start a
ncodesession. While the app is running under your user account, everyncodecommand except--versionand--helprefuses to start and exits with status 3, naming the running app. Starting it with a different home folder does not change this. - Exit
ncodebefore you reopen the app. The app does not check for a runningncodesession, so this rule is yours to keep. - Keep both on the same version. If
ncodesays the database needs an upgrade, open the app once and quit it. If it says the database is newer than it understands, updatencode.
What only the app does#
Some background work runs only inside the desktop app, and only while it is running:
- Scheduled tasks fire only in the app.
ncodecan list, create, edit, switch on or off and "run now" a task, but a schedule never fires from the terminal. - Storage retention (deleting or pruning old sessions on a schedule) runs once a day in the app. The settings are shared, but
ncodedoes not apply them. - Workflow runs left behind by a crash are tidied up by the app.
When ncode refuses to start#
With the app open, every ncode command except --version and --help stops at once with exit code 3:
The ncode app is open, and only one of them can use your conversations at a time. Quit the ncode app, then run ncode again.
Quit the app (⌘Q, closing its window is not enough), then run the command again. To continue a conversation you started in the app, open it with /resume in the session, or ncode --resume <conversation-id>.
On the other side, reopen the app only after you have quit every ncode session (Ctrl+C twice).
Upgrading together#
Update both on the same day. The database format changes with the app, and ncode refuses a database it does not understand rather than risk it:
ncode says | Do this |
|---|---|
This ncode database needs an upgrade that only the ncode app makes. | open the app once, quit it, run ncode again |
This ncode database was upgraded by a newer ncode app than this ncode supports. | update ncode: re-run the installer |
Neither message changes anything in the database.
How the two differ#
| Topic | Desktop app | ncode |
|---|---|---|
| Interface | a native window | full-screen terminal, plain line mode, headless -p |
| Scheduled tasks | fire on their schedule | can be created, edited and run now; never fire |
| Storage retention | applied once a day | the settings are shared; not applied |
/resume | resumes the last stopped run | opens a conversation (the run is /resume-run) |
| Model and approvals | controls in the composer | /model, /swarm_model, /approval, /trust |
| Answering approvals | buttons | the keys y Y A d D n |
| Provider presets | enter the details yourself | presets for Anthropic, OpenAI, OpenRouter, DeepSeek, Ollama, LM Studio and any OpenAI-compatible endpoint |
MCP .mcp.json import | no | yes |
| Settings from scripts | no | ncode config |
| Themes | several themes, each dark and light | dark and light, with an accent colour |
The desktop documentation has its own page on using the app with the CLI.