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).
If you start the app while a ncode session is already open, the session shows a banner shortly after: The ncode app is open on the same database. Quit it, or stop your runs here and quit (Ctrl-C twice). Nothing is lost; quit one of the two.
Upgrading together#
Update both on the same day: ncode 0.3.0 (the app) goes with ncode 0.3.0. The app and the command are numbered separately, so their versions can differ; both are the 0.2 line. The database format changes with the app, and ncode refuses a database it does not understand rather than risk it. A ncode 0.1.0 refuses a database that a 0.2 app has upgraded, so update the command after the app, with the installer:
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. The 0.2.0 message adds Install the ncode CLI that matches your ncode app (ncode --version shows this one: …) |
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 |
| Ultra | missions: an orchestrator, workers and validators, with Mission Control | big tasks run as workflows; missions are not in ncode yet |
| Worker and Validator model | Worker model and Validator model settings | the same two settings, with the same words (the Validator model only matters for missions in the app) |
| Scheduled tasks | fire on their schedule | can be created, edited and run now; never fire (the library says so) |
| 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, /worker_model, /approval, /trust |
| Answering approvals | buttons | the keys y Y A d D n; Read-only asks in both, with approve, deny and deny and stop |
| Rewind a turn | edit and resend, which restores no files | /rewind and /undo put back the conversation, the files, or both |
| 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 | the same eight palettes, each dark and light, with an accent colour |
The desktop documentation has its own page on using the app with the CLI.