Skip to content
DocumentationQuickstartIntegrationsReferenceTroubleshooting
DEEN

Integration

Command line

The command line opens your workspace from any terminal: search, save files and whole folders, check the state. It also registers knowmind in other tools and acts as a bridge for programs that speak MCP only locally.

Audience
Experienced users and developers driving knowmind from scripts, pipelines or local tools. You do not need it for working in the browser.

Prerequisites

  • Node.js 20 or newer (check: node --version)
  • An email address for the knowmind account
  • Write access in your home directory for ~/.knowmind/config.json

Steps

  1. 1

    Create your knowmind account

    Enter your email address at knowmind.de. You receive a sign-in link by mail and use it to sign in. There is no password.

    Then create your workspace: name, short name and plan. The Private plan costs 0 € and is enough for this guide; the pricing page lists the others.

    Outcome: The welcome screen is open, offering “start by writing” and “connect my AI tool”. Three starter cards are already in your workspace.

  2. 2

    Install the command line

    bash
    npm install -g knowmind

    The knowmind command is then available system wide. knowmind help prints name and version on its first line and lists every command. Without installing, every command also runs as npx -y knowmind ….

    Note

    What this command downloads

    The command line alone, a small piece of software under Apache-2.0. No content, no credentials. It reaches your workspace only after the sign-in in the next step.

    Outcome: knowmind help prints name and version on its first line.

  3. 3

    Sign in

    Create a key in the Cockpit under keys — read is enough for searching, write is needed for saving. Then:

    bash
    knowmind login --token kmt_YOUR_KEY

    The key lands in ~/.knowmind/config.json, with restricted file permissions on Unix. In pipelines, pass it through the environment variable KNOWMIND_TOKEN instead; KNOWMIND_API_URL points at a different endpoint if you need one.

    Outcome: knowmind config shows endpoint and key prefix, knowmind health the state of the service.

  4. 4

    First hit

    Save something, then search for it. In a fresh workspace the search otherwise answers with the three starter cards, marked as a starting point rather than a solid hit.

    bash
    echo "Invoices always go to head office, never to a branch." \
  | knowmind upload - --title "Invoice routing"

knowmind search "Where do invoices go?"

    Outcome: The search returns the entry with its source. Both commands exit with 0 on success and write their result to stdout — usable from a script.

  5. 5

    Sync a folder

    A whole folder goes in one run — and on the second run, only what changed. The file .knowmind-manifest.json inside the folder keeps that state, recognised from the file contents.

    bash
    knowmind sync ./docs
knowmind sync ./docs --ext .md,.txt --verbose

# Knowledge in the Open Knowledge Format, such as an openwiki/ folder:
knowmind sync ./openwiki --okf

    Pages in the Open Knowledge Format keep their provenance, review state and expiry date, as far as the page states them.

    Outcome: The run reports for each file whether it was new, changed or unchanged.

  6. 6

    Register other tools

    The command line writes the MCP settings of other tools itself:

    bash
    npx -y knowmind install cursor --token kmt_YOUR_KEY
npx -y knowmind install list     # show all targets

    Targets are cursor, vscode, windsurf, antigravity, zed, jetbrains, gemini, codex, claude-code, claude-desktop and all. --print only shows the entry, --project writes it into the project folder.

    Outcome: After a restart the tool lists knowmind as an MCP server.

Status display and automatic upkeep

knowmind status --line prints one line for the status bar of an AI tool: steady green while the service is reachable, flickering during a query, red on an outage. It reads a short-lived cache and never holds the tool up.

json
{
  "statusLine": {
    "type": "command",
    "command": "knowmind status --line",
    "refreshInterval": 500
  }
}

The refreshInterval belongs there: without it Claude Code only redraws the line on events, so the flicker never shows. knowmind init --client claude-code sets up the status bar and the rules for automatic upkeep that way, leaving an existing status bar of your own untouched.

As a local MCP bridge

Tools that speak MCP only over stdio start the command line as a bridge. The key stays in the command line’s own configuration; the AI tool never sees it.

json
{
  "mcpServers": {
    "knowmind": {
      "command": "knowmind",
      "args": ["mcp"]
    }
  }
}

Codex reads its servers from ~/.codex/config.toml, where the same entry reads:

toml
[mcp_servers.knowmind]
command = "knowmind"
args = ["mcp"]

Verify the result

The command line is ready when all three hold:

  • knowmind health reports the service as reachable.
  • knowmind stats names the number of entries and relations.
  • knowmind search "your question" returns hits from your own store.

Troubleshooting

Error messageCauseResolution
command not found: knowmindThe global npm directory is not on the search path.Find the path with npm config get prefix and add it to your search path. Or call every command as npx -y knowmind ….
EACCES on npm install -gThe global directory requires elevated rights.Install with elevated rights, or move the npm directory to one of your own: npm config set prefix ~/.npm-global.
login: the key is rejectedThe key has been revoked or was copied incompletely.Create a new key in the Cockpit and run the command again. Watch for stray spaces when copying.
sync: missing permissionThe key only carries the read right.Create a key with read and write in the Cockpit and revoke the old one.
What we tested
Tested on 19 October 2026 with version 0.4.5 from the npm registry: sign-in with a key and search both work, and the hit came back in about 0.3 seconds in that run. Account and workspace were created and removed over the same route.

Related