Connect

CLI

vinc reads and writes your graph from a terminal. Use it to look something up quickly, or in a script or an agent that can run shell commands.

The account CLI is published in vincs 0.1.0 and reports CLI version 0.9.7. Package and CLI versions are independent. Older desktop installers may have different commands; check vinc --help and vinc <command> --help.

First step: set a terminal key

For the account graph, create a member key on your account page: vinc_ro_ for reading, or vinc_sk_ for writing. There is no vinc login. Desktop sign-in changes the default graph target; terminal commands need their own API key. The CLI does not store this key on disk.

In Bash, prompt for the key so it stays off screen and out of shell history. On a shared machine, pass it to one command instead of exporting it. Keep the real key out of command text and shell profile files. The local graph needs no account key.

read -r -s -p "Vinc API key: " VINC_API_KEY
printf '\n'
VINC_API_KEY="$VINC_API_KEY" vinc --target account whoami
unset VINC_API_KEY

Install

For account graph commands, install vincs with Python 3.11 or later. It includes the SDK and the vinc CLI on Windows, macOS and Linux. For local storage and offline models, use the desktop or standalone CLI runtime.

python -m pip install vincs
vinc --version
vinc --help

For the desktop runtime, use the platform steps below.

In the desktop app, open Settings > AI connections and press Set up next to Command line. The app links vinc into /usr/local/bin, or ~/.local/bin when that is not writable. If the app says the folder is not on your PATH, add the line it shows to your shell profile.

The package installs vinc at /usr/bin/vinc. There is nothing to set up.

vinc --help

Standalone local CLI

For local storage and offline models, a Linux x86_64 standalone CLI archive is prepared separately. It has not been published yet. The pip package serves account commands now. Use the archive commands below only after the download page lists a published archive and checksum.

The archive contains only vinc and LICENSE. It installs no desktop app, GTK or WebKit. Its download routes are the CLI archive and SHA256 checksum. On macOS and Windows, use the desktop installation methods above.

set -eu
curl --fail --location --output Vinc-cli-linux-x86_64.tar.gz https://vincs.io/dl/linux-cli
curl --fail --location --output Vinc-cli-linux-x86_64.tar.gz.sha256 https://vincs.io/dl/linux-cli.sha256
sha256sum --check Vinc-cli-linux-x86_64.tar.gz.sha256
tar --extract --gzip --file Vinc-cli-linux-x86_64.tar.gz
install -D -m 755 vinc "$HOME/.local/bin/vinc"
export PATH="$HOME/.local/bin:$PATH"
vinc --version
vinc --help

Extract only after the checksum passes. install sets executable permissions. The PATH line applies to the current shell; add it to your shell profile to keep it. Compare vinc --version with the published release version.

Quickstart

Set VINC_API_KEY in the current terminal, then read your account graph with these commands. With the standalone local runtime, use --target local to read this device’s graph.

vinc --target account whoami                                   # which graph am I on
vinc --target account search --query "release notes"           # search text and nodes
vinc --target account brief --query "Why are tokens OKLCH?"    # one answer with its sources
vinc --target account node get concept:design-0                # one node by id
vinc --target account doc ls                                   # documents, newest first

Choose the graph

Graph commands work on one of two graphs. local is the graph on this device; account is your account graph on vincs.io.

Choice	Order it is read in
Graph	`--target`, then `VINC_TARGET`, then the app's mode (local or account), then `local`
Space (account only)	`--space`, then `VINC_SPACE`, then `personal`. A team is its team id.

For the account graph, set a key from your vincs.io account page. Use a read-only key (vinc_ro_) for reading and a write key (vinc_sk_) only where you change things. VINC_API_URL changes the API address if you need to.

read -r -s -p "Vinc API key: " VINC_API_KEY
printf '\n'
export VINC_API_KEY
vinc --target account brief --query "release checklist"
vinc --target account --space <team id> search --query "onboarding"

Store and device operations such as backup, export and serve require the local target. They reject account whether it comes from --target, VINC_TARGET or app mode; use --target local. refs check reads files only. MCP stdio and host configuration have separate policies on the command reference.

Output

--format picks the output: human for reading, json for one JSON object, ndjson for one row per line. Without it, a terminal gets human and a pipe gets json. --json is short for --format json, and VINC_FORMAT sets a default.

vinc --target account search --query "contrast" --format ndjson | jq -r '.doc_title // .title // .id'

Writes and deletes

Commands that delete or merge (delete, edge delete, merge, doc rm, and call on those tools) ask you to type yes in a terminal. In a script there is no one to ask, so pass --yes; without it the command stops with exit code 2.

Exit codes

Code	Meaning
`0`	Success.
`1`	The tool answered with an error, or found nothing (`status: none`).
`2`	The command was used wrongly, or a delete was not confirmed.
`4`	Account target: the key is missing or refused.
`5`	Account target: the API could not be reached.
`6`	Account target: the daily limit is used up. Wait for `Retry-After`.

A failure is never printed as an empty result, so a script can trust an empty list.

Every command with its options is on the command reference. To call Vinc from code without the CLI, use the API or vincs.

CLI