#Command-line interface (CLI)

The wwkg CLI is the main way to run a node, manage workspaces, load data, and query a WWKG server. All commands are subcommands of wwkg.

#Global options

These apply before the subcommand runs.

#Commands overview

#Node Runtime

Run or destroy the local node process.

#Start

• --host <host> — Bind address (default: 0.0.0.0).
• --ephemeral — In-memory storage; data is lost on shutdown.
• --relay — Use relay servers for NAT traversal (connectivity to peers behind firewalls).
• --kill — If another wwkg node serve is already running, stop it first and then start.
• --no-log-file — Do not write rotating log files (stderr only).

#Destroy

Permanently removes the data directory. The server must be stopped first. Use --yes to skip the confirmation prompt.

#Graph

Run queries and updates against graph data on a running node. By default the CLI discovers a local node; use global --node or --ticket to target a specific node.

#Options

• --node <id> — Select a node by ID, key-id, name, or unique prefix.
• --ticket <ticket> — Connection ticket for direct connection (env: WWKG_TICKET).

#Query

Execute a SPARQL query. Default server: http://127.0.0.1:4242. Output: JSON (default) or TSV.

#Explain

Show the query execution plan.

#Update

Execute a SPARQL update (e.g. INSERT DATA, DELETE DATA).

#Validate

Validate a SPARQL statement without executing it. Use the global --json flag to return a machine-readable validation report with source spans for parser diagnostics.

Returns:

span.start is inclusive and span.end is exclusive. Columns are 1-based character positions; offsets are byte offsets into the input string.

#Provenance

Explain why an inferred triple exists: the rule(s) that derived it and the premises they consumed. Each row is tagged rule or premise. An asserted (non-inferred) triple yields no rows, so the command also answers “is this fact stored or inferred?”. Sugar over a SPARQL 1.2 reification query against the reserved urn:wwkg:provenance graph.

#Branch

• wwkg graph branch list — List branches.
• wwkg graph branch create <name> [--from <branch>] — Create a branch (optionally fork from another).
• wwkg graph branch delete <name> — Delete a branch.

#Node

Manage nodes (generic commands for any node kind).

• wwkg node list — List all nodes (hosts and gateways).
• wwkg node host status, wwkg node gateway status, wwkg node custody status — Show daemon profile for the host, gateway, or custodian process (use the global --json flag for NodeProfile JSON).
• wwkg --node <name-or-id> system version — Show CLI version plus the selected node’s version, Node ID, and host workspace details.
• wwkg node destroy [--purge] — Destroy a node’s local data.
• wwkg node rename <name> — Set a node’s human-readable name.
• wwkg node host use <prefix> — Set the host used when socket discovery is unavailable.

#Workspace

Create and manage workspaces (encrypted graphs). Workspace IDs use the form urn:wwkg:workspace:<uuid>.

#Create, List, Info, Use, Current

• wwkg workspace create --name <name> — Create a new workspace.
• wwkg workspace list — List all known workspaces.
• wwkg workspace info <id> — Show details for a workspace.
• wwkg workspace use <id> — Set the active workspace.
• wwkg workspace current — Show the currently active workspace.

#Owner and key

• wwkg workspace owner <id> — Display the owner’s identity.
• wwkg workspace rotate-key <id> — Rotate the workspace encryption key (owner only).

#Membership

• wwkg workspace invite <id> --identity <identity> --role <Reader|Writer|Admin> — Invite a member (Admin or Owner only).
• wwkg workspace members <id> — List all members.
• wwkg workspace accept-invite <id> — Accept a pending invitation.
• wwkg workspace decline-invite <id> — Decline a pending invitation.
• wwkg workspace suspend <id> --identity <identity> — Suspend a member (Admin or Owner only).
• wwkg workspace reactivate <id> --identity <identity> — Reactivate a suspended member.
• wwkg workspace revoke <id> --identity <identity> — Revoke a member and rotate the workspace encryption key (Admin or Owner only).

#Delete

• wwkg workspace delete <id> — Delete a workspace and its local data (owner only).

#Version

Prints local CLI version and protocol information, then queries the selected node and prints its version, Node ID, role, and host workspace details. Without a selector, the default localhost node is queried. With --node, --host, --port, or --ticket, that target is queried instead.

If the node cannot be reached, the command still prints the CLI version and includes a node error row. Honors --json, --toml, and --cbor.

#Upgrade

• --check — Exit 0 if up to date, 1 if an upgrade is available.
• --dry-run — Print what would be downloaded without doing it.
• --rollback — Restore the previous binary (.prev).
• --version <version> — Install a specific version instead of the latest.

#MCP Server

Run a Model Context Protocol server over stdio. Every wwkg leaf subcommand is exposed as an MCP tool an MCP-aware client (Claude Desktop, Claude Code, Cursor) can invoke directly — read-only tools carry readOnlyHint: true so the host can auto-approve them; mutating tools carry destructiveHint: true so the host prompts before invocation.

See the MCP Server guide for end-to-end setup, client configuration examples, and the tool-naming convention.

#Format

Format a SPARQL statement. Input: file path, inline string, or stdin if omitted.

#Upload

Batch-upload RDF from a file or directory through a staging branch. For a single file: upload that file. For a directory: recursively upload supported RDF files and merge the staging branch into the target branch.

• path — File or directory (default: .).
• --graph <iri> — Named graph IRI (single-file: target graph; directory: omitted, see --graph-base).
• --graph-base <uri> — IRI prefix for per-file graph IRIs in directory uploads (default: file://).
• --node <node> — Select the target node by ID, key ID, name, or unique hex prefix.
• --branch — Branch to load into.
• --workspace — Workspace to target (urn:wwkg:workspace:<uuid>).