@mindwebs/cli

Your knowledge graph from the terminal. Interact with MindWebs via 19 commands — zero local database required.

Install

npm install -g @mindwebs/cli
# or
pnpm add -g @mindwebs/cli

Quick start

mindwebs login          # Opens browser for authentication
mindwebs search "CRISPR"
mindwebs create --name "New Idea" --type Concept
mindwebs read <uuid>
mindwebs rels <uuid>    # Show relationships
mindwebs stats           # Node/relationship counts

Commands

| Command | Description | |---------|-------------| | login | Sign in (opens browser) | | logout | Delete local credentials | | status | Show auth status | | search <query> | Full-text search | | list [--type Type] | Browse nodes by type | | read <uuid> | Read a single node | | create | Create a new node | | update <uuid> | Update node properties | | delete <uuid> | Delete a node | | connect | Create a relationship | | disconnect <uuid> | Delete a relationship by its UUID | | retype <uuid> [type] [--set k=v] | Change a relationship's type and/or patch its properties (UUID stays) | | batches [--limit n] [--agent prefix] [--since iso] [--until iso] | List your write batches (ingests, imports), newest first, with who wrote them | | batch <batchId> [--full] | Show what one batch wrote; use before undo | | undo <batchId> | Delete everything one of your batches created (not reversible) | | import-session <file> | Import an agent session transcript (.jsonl) into the graph | | export [--format fmt] [--limit n] [--content] | Export everything in scope: json, jsonld, ro-crate, bibtex, ris or csv; --content includes stored text so the export can be imported back | | reconcile <manifest-file> | Preview or apply a reviewed batch with a durable receipt | | rels <uuid> | Query relationships | | path <from> <to> | Find shortest path | | stats | Graph statistics | | types | Relationship type counts | | docs <query> | Search documents | | scopes | List accessible graphs | | schema | Get graph schema | | me | Show your profile | | chat [question] | Interactive REPL or one-shot question against the agent | | session list --device <device-id> | Find saved conversations and live terminals on one owned device | | session propose <proposal-file> | Save a native message for review in Sessions | | session action <receipt-id> | Read the same saved action and delivery status | | mindspace <slug> | Open a full-pane interactive 3D mindspace seeded from a node | | mcp | Run the stdio MCP server (for Claude Desktop / Code / Cursor) |

Flags

• --json — Output as JSON
• --quiet — Output IDs only (for piping)
• --scope <scope> — "mind" (default), "public", or Hivemind UUID

Reviewed graph batches

Use reconcile when a source comparison has produced an explicit set of accepted changes. This command requires --scope, even for your personal Mind. The default invocation previews the changes and conflicts:

mindwebs --scope <Hivemind-UUID> --json reconcile review.json
mindwebs --scope <Hivemind-UUID> --json reconcile review.json --apply --digest <preview-digest>

The manifest contains a unique batchId, a review reference, sources, and operations. Each operation names its supporting sourceIds. It can create an ordinary node, patch properties with their expected old values, or create or patch a directed relationship. It cannot delete records, merge identities, or change access.

Apply checks access and expected values again. Graph changes, history events and the receipt commit in one transaction. A conflict writes nothing and exits with status 2. Repeating an applied batch with the same content returns its existing receipt. Reusing its ID with different content fails.

Relationship property edits are recorded in history, but their current undo handler rejects reversal. To correct one, preview a new manifest with explicit expected values. A retry also fails if the original batch's history is missing or has been undone.

The receipt identifies the authenticated account that applied the batch. Reviewer, agent and source fields are declared provenance; they do not grant access or prove that the named person approved anything. Preview is a read of current state, so changes made by someone else can still prevent a later apply.

Find a saved session

Use mindwebs devices to get the exact owned device ID, then:

mindwebs --scope mind --json session list --device <device-id>

This reads the same bounded Codex and Claude Code metadata as Sessions, including saved desktop conversations that have no terminal. Check scan.state and the catalog's source coverage before treating the result as a complete inventory. An unavailable source can coexist with usable sessions from another source. Listing needs file-read permission and personal Mind scope. It does not connect to or control a provider session. mindwebs sessions remains the terminal list.

Review a native session message

With a gateway that supports native proposals, session propose saves a message for review in the target's Sessions view. It does not send the message itself. Use the exact device, source and thread returned by the catalog; a project name or directory is not a session identity.

mindwebs --scope mind --json session propose ./proposal.json
mindwebs --scope mind --json session action <receipt-id>

The JSON file contains version: 1, target (deviceId, provider: "codex", sourceId, threadId), action: "send", expectedTurnId: "" and text. For action: "steer", expectedTurnId must name the active turn. Text is limited to 16 KiB in UTF-8. The result includes the approval receipt and a review link. Open it, read the saved text, then approve or reject. Sending requires a supported native controller on that exact session. Your draft stays separate.

An uncertain response is not retried automatically. Use session action with the returned receipt ID to check the same request. A consumed approval means the send was authorized; only matching delivery evidence confirms acceptance. This route requires the personal owner and enabled session tools. It does not support delegated identities, shared scopes, new sessions or provider approvals.

Chat

mindwebs chat                       # Interactive REPL (Ctrl-D, /quit, or /exit)
mindwebs chat "what's in my graph?" # One-shot question; streams and exits
echo "summarize this" | mindwebs chat  # Read question from stdin
mindwebs chat --json "hi"           # Buffer full response as a single JSON object
mindwebs chat --ndjson "hi"         # Passthrough raw NDJSON events
mindwebs chat --no-history "hi"     # Skip persisting this session
mindwebs chat --graph <id> "hi"     # Target a specific graph

History is appended to $XDG_CONFIG_HOME/mindwebs/chat/<graph-id>.jsonl (defaults to ~/.config/mindwebs/chat/).

Mindspace (mw <slug>)

The CLI installs as both mindwebs and mw. The short mw form has a shorthand for the new mindspace subcommand: any bare slug-shaped argument ([a-z][a-z0-9-]*) is routed to it.

mw my-project                      # = mindwebs mindspace my-project
mw mindspace my-project            # explicit form
mw mindspace --demo                # synthetic graph, no network — good for screenshots
mw mindspace my-project --depth 2  # walk 2 hops out (capped at limit)
mw mindspace my-project --invoke brainviewer  # open the threejs brain viewer on exit

Resolves the slug via search_nodes (preferring Project / Concept / Document matches), pulls a 1-2 hop neighborhood through query_relationships, collapses any Hyperedge-typed nodes into proper hyperedges, and opens a full-pane Hologram with the existing arrow-key + q browse loop.

To put mw on PATH after a local build:

ln -sf "$(pwd)/dist/index.js" ~/.local/bin/mw && chmod +x ~/.local/bin/mw

MCP server (mindwebs mcp)

mindwebs mcp is a stdio MCP server that forwards every request to the MindWebs gateway with the credentials from mindwebs login. Add it to Claude Desktop / Cursor / Claude Code:

{
  "mcpServers": {
    "mindwebs": {
      "command": "mindwebs",
      "args": ["mcp"]
    }
  }
}

Flags:

• --transport <mode> — stdio (default). http is not supported yet and exits with a message saying so.
• --require-login / --no-require-login — default on. Refuses to start without either a credentials file (mindwebs login) or MINDWEBS_ID_TOKEN env var.

MindWebs Home — device mesh

The mindwebs device subcommands manage enrollment into your lab's private Headscale (BSD-3) mesh. These are only useful inside a MindWebs Home install; cloud users can skip the section.

# In Admin > Devices, generate a single-use preauth key, then enroll this device
mindwebs device add --preauth-key tskey-... --login-server https://mindwebs-mesh.local

# Show this device's mesh status
mindwebs device status

# List every device currently on the tailnet (JSON)
mindwebs device list

Prerequisites

Install the Tailscale client separately — MindWebs doesn't bundle it:

• macOS: brew install tailscale
• Linux: curl -fsSL https://tailscale.com/install.sh | sh
• Windows: winget install tailscale.tailscale

If tailscale isn't on PATH when you run a device command, the CLI prints the appropriate install command for your OS and exits non-zero.

Env overrides

• MINDWEBS_HEADSCALE_URL — default --login-server for device add. Set automatically inside the Home bundle.
• MINDWEBS_TAILSCALE_BIN — path to the tailscale binary (override for non-standard installs).

Architecture

The CLI is a thin HTTP client that hits the MindWebs MCP gateway for most commands. All intelligence (search, ingestion, ACL) runs server-side.

mindwebs mcp --direct, an MCP server that opens your own Neo4j database directly, is part of the MindWebs Home build only. Home builds the CLI from source with pnpm build, and --direct starts there because MINDWEBS_HOME=true and you own the database. Anywhere else it would open the database around every hosted safeguard, so it refuses. The package on npm is built with pnpm build:npm, which leaves that server out; there --direct says where it lives and exits.

License

Proprietary — see mindwebs.io