CLI

Command line

Most of what the app does on screen, the vinc-sidecar command can do too. Reach for it to automate something, to bring in files in bulk, or to put a backup on a schedule.

Getting the command

This page writes the engine by its real name, vinc-sidecar, because that name works on every platform. There is no separate CLI download yet, so today it reaches you two ways.

From a checkoutRun it as a module: python -m api.cli search --query "…". Everything on this page works this way.

With the desktop appThe bundled engine binary is named vinc-sidecar and takes the same subcommands. The Linux packages put it on your path; on macOS and Windows it sits in the application folder, so call it by its full path or alias it yourself. Since v0.8.3 the Linux packages also let you type vinc followed by any verb on this page: the app binary hands those straight to the engine instead of opening a window. That shortcut is Linux only so far.

If you only want to connect an assistant, you do not need any of this. Settings → Connections in the app does the same registration.

Nearly every command wants --owner. Data is never allowed to sit without an owner. If you also use the desktop app, pass the same owner it uses or you will be looking at a different map.

Storage location comes from --data or the MEMORY_DATA_DIR environment variable, defaulting to ~/.vinc/db. Point it somewhere else and you get a different map. "I added it but the app does not show it" is usually this.

Connecting an assistant

The most-used branch. Per-host notes are in Setup.

vinc-sidecar mcp installRegister with a local host. Writes the config for you and preserves existing servers.

vinc-sidecar mcp uninstallRemove that registration.

vinc-sidecar mcp manualPrint the stdio config snippet for hosts with no installer. Paste and you are done.

vinc-sidecar mcp serveRun the server over stdio directly. Normally the host launches it, so you rarely touch this.

vinc-sidecar mcp serve-httpStreamable HTTP transport (remote profile). This is what the hosted hub runs.

vinc-sidecar mcp install --client desktop|code|cursor|codex

If you use the app, the buttons in Settings → Connections do the same thing. The terminal is only needed for automation.

Finding and traversing

vinc-sidecar searchRuns meaning search and keyword search together and combines them.

vinc-sidecar recallList recent episodes, optionally narrowed by domain.

vinc-sidecar graphSubgraph from a seed node out to a given depth.

vinc-sidecar decideGather what bears on a topic, including conflicts.

vinc-sidecar domainsThe topics your material actually formed. Discovered from data, not a fixed list.

vinc-sidecar planPrint the query plan without executing. For when you want to know why you got that result.

vinc-sidecar search --query "vector index" --top-k 10

Preference signals

What you pull up often feeds back into ranking. These three leave that signal.

vinc-sidecar pinPin or unpin an episode.

vinc-sidecar tagAdd your own tags.

vinc-sidecar touchRecord that you looked something up again.

Pins and tags are yours, so they never go into a pack. Share it and they stay behind.

Documents

The source text is canonical (Chunk=SSoT). Concepts in the map point back at it.

vinc-sidecar doc putStore or edit source text. --file takes .md, .txt, .rst, .pdf directly. Omit --id to create, and the new id comes back.

vinc-sidecar doc getReconstruct the text from its chunks, verifying integrity by hash.

vinc-sidecar doc rmDelete a document. Chunks and identity go together.

vinc-sidecar doc lsList documents.

vinc-sidecar graph-mdbuild writes your topics and vocabulary into a conventions file, check verifies its shape. Exits 0, 1, or 2.

vinc-sidecar doc put --owner you --file notes/design.md --title "Design notes"

Moving and keeping

vinc-sidecar shareBuild a share pack. Scope it by domain or tags, and --depth decides how much comes along.

vinc-sidecar importBring a pack in, re-stamped to your owner. The merge is idempotent, so importing twice does not duplicate.

vinc-sidecar backupConsistent snapshot plus a packs and profile archive. Routes around locked files safely.

vinc-sidecar serveRun the loopback sidecar HTTP server. The app uses this internally; you rarely call it.

vinc-sidecar onboardCreate the local credential (argon2id passphrase).

vinc-sidecar activateExport owned memory as a portable context pack, with an MCP manifest.

vinc-sidecar share --owner you --domain research --out research.vincpack vinc import --pack research.vincpack --owner you

share and backup are for different things. A share pack hands one slice to someone else; a backup carries everything to a new machine.

Getting the exact arguments

Every command takes --help, and that is always more current than this page.

vinc-sidecar --help vinc doc put --help

This page is a map of what exists. For exact arguments, --help is the source of truth.