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.
| Option | Description |
|---|---|
-C <path> | Run as if started in <path> (like git -C). |
--node <id> | Select a node by ID or unique prefix (under the data root nodes/). Omit to use --port, WWKG_NODE, the .default marker, or auto-select if exactly one node exists. |
--port <port> | Select the node that owns the given port (via .port-N marker files). Mutually exclusive with --node. |
Commands overview
| Command | Purpose |
|---|---|
wwkg node | Run and manage the local node (serve, destroy, identity, service install/start/stop/status). |
wwkg client | Query or update a remote server (SPARQL query/update, import, branches, status). |
wwkg node | Initialize or manage the local node (identity, default workspace). |
wwkg workspace | Create, list, and manage workspaces (members, keys, invitations). |
wwkg version | Print version and protocol information. |
wwkg upgrade | Upgrade or rollback the wwkg binary. |
wwkg format | Format a SPARQL statement (file, inline, or stdin). |
wwkg load | Batch-load RDF files (.ttl, .nt, .rdf) from a file or directory into the graph store. |
Node Runtime
Run or destroy the local node process.
Start
wwkg node serve [options]--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 anotherwwkg node serveis already running, stop it first and then start.--no-log-file— Do not write rotating log files (stderr only).
Destroy
wwkg node destroy [--yes]Permanently removes the data directory. The server must be stopped first. Use --yes to skip the confirmation prompt.
Client
Run queries and updates against a running server. By default the client discovers a WWKG server on the local network via mDNS.
Options
--ticket <ticket>— Connection ticket for direct connection (env:WWKG_TICKET).--http— Use HTTP transport instead of the default protocol.
Query
wwkg client query "<SPARQL query>" [--server <url>] [--branch <name>] [--workspace <id>] [--format json|tsv]Execute a SPARQL query. Default server: http://127.0.0.1:4242. Output: JSON (default) or TSV.
Explain
wwkg client explain "<SPARQL query>" [--server <url>] [--branch <name>] [--workspace <id>]Show the query execution plan.
Update
wwkg client update "<SPARQL update>" [--server <url>] [--branch <name>] [--workspace <id>]Execute a SPARQL update (e.g. INSERT DATA, DELETE DATA).
Import
wwkg client import <file> [--server <url>] [--branch <name>] [--workspace <id>] [--graph <iri>]Import an N-Triples file into the graph store. Optional --graph for target graph (default graph if omitted).
Branch
wwkg client branch list [--server <url>]— List branches.wwkg client branch create <name> [--from <branch>] [--server <url>]— Create a branch (optionally fork from another).wwkg client branch delete <name> [--server <url>]— Delete a branch.
Status
wwkg client status [--timeout <seconds>]Check WWKG network status (default timeout: 5 seconds).
Node
Manage nodes (generic commands for any node kind).
wwkg node list— List all nodes (hosts and gateways).wwkg host status,wwkg gateway status,wwkg custody status— Show daemon profile for the host, gateway, or custodian process (use the global--jsonflag forNodeProfileJSON).wwkg node version— Show the running node’s version.wwkg node destroy [--purge]— Destroy a node’s local data.wwkg node rename <name>— Set a node’s human-readable name.wwkg host default <prefix>— Set the default host by ID or unique prefix.
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
wwkg versionPrint version and protocol information.
Upgrade
wwkg upgrade [--check] [--dry-run] [--rollback] [--version <version>]--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.
Format
wwkg format [<file>|<SPARQL>]Format a SPARQL statement. Input: file path, inline string, or stdin if omitted.
Load
wwkg load [path] [--graph <iri>] [--graph-base <uri>] [--server <url>] [--branch <name>] [--workspace <id>]Batch-load RDF from a file or directory. For a single file: load that file. For a directory: recursively load all .ttl, .nt, and .rdf files via HTTP PUT (replacing the target graph).
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 loads (default:file://).--server— Server URL (default:http://127.0.0.1:4242).--branch— Branch to load into.--workspace— Workspace to target (urn:wwkg:workspace:<uuid>).