#Command-line interface (CLI)

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

#Global options

These apply before the subcommand runs.

#Commands overview

#Node Runtime

Run or destroy the local node process.

#Start

legra 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 another legra node serve is already running, stop it first and then start.
• --no-log-file — Do not write rotating log files (stderr only).

#Destroy

legra node destroy [--yes]

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: LEGRA_TICKET).

#Query

legra graph query "<SPARQL query>" [--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

legra graph explain "<SPARQL query>" [--branch <name>] [--workspace <id>]

Show the query execution plan.

#Update

legra graph update "<SPARQL update>" [--branch <name>] [--workspace <id>]

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

#Validate

legra graph validate "<SPARQL statement>"

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.

legra --json graph validate 'SELECT * WHERE {
  ?s ?p ?o dddd
}'

Returns:

{
  "valid": false,
  "error": "statement failed validation: unexpected input at line 2, columns 12-15",
  "diagnostic": {
    "message": "unexpected input at line 2, columns 12-15",
    "span": {
      "start": { "line": 2, "column": 12, "offset": 28 },
      "end": { "line": 2, "column": 16, "offset": 32 }
    }
  }
}

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

#Provenance

legra graph provenance <subject> <predicate> <object> [--branch <name>] [--workspace <id>] [--format json|tsv]

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:legra:provenance graph.

legra graph provenance http://ex.org/Bob http://ex.org/childOf http://ex.org/Alice

#Branch

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

#Node

Manage nodes (generic commands for any node kind).

• legra node list — List all nodes (hosts and gateways).
• legra node host status, legra node gateway status, legra node custody status — Show daemon profile for the host, gateway, or custodian process (use the global --json flag for NodeProfile JSON).
• legra --node <name-or-id> system version — Show CLI version plus the selected node’s version, Node ID, and host workspace details.
• legra node destroy [--purge] — Destroy a node’s local data.
• legra node rename <name> — Set a node’s human-readable name.
• legra 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:legra:workspace:<uuid>.

#Create, List, Info, Use, Current

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

#Owner and key

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

#Membership

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

#Delete

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

#Version

legra system version
legra --node <name-or-id> 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

legra system 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.

#MCP Server

legra system mcp serve

Run a Model Context Protocol server over stdio. Every legra 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

legra graph format [<file>|<SPARQL>]

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

#Upload

legra graph upload [path] [--graph <iri>] [--graph-base <uri>] [--target-branch <name>] [--workspace <id>]

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:legra:workspace:<uuid>).