Command Line Interfaces

ShrikeDB has two command-line surfaces, and they are meant for different jobs.

CLI Best for Entry point

Interactive shell

Exploring a running server, selecting a database, running Cypher, checking health, listing connector sources, and doing small imports.

shrikedb-cli or shrikedb --cli

Operational onboarding CLI

Scriptable dataset inspection, dataset loading, ontology import, and demo validation through HTTP onboarding endpoints.

shrikedb onboard …​ and shrikedb ontology …​

The CLI is not the user-admin tool. Tenant, user, role, policy, and API-key lifecycle live in the multi-tenant identity service.

Choose an installed client

Use the supplied shrikedb-cli executable, or the shrikedb --cli mode included with your server package. The examples assume these executables are on your command path.

The server binary can also launch the interactive shell when invoked with --cli. Interactive terminals use the friendly REPL foundation: editable input, persistent history, registry-backed completion, contextual prompts, multiline query entry, and redacted diagnostics. When stdin is not a terminal, the CLI keeps the plain line-by-line loop so scripts can continue piping commands.

Interactive Shell

Start the shell against a running server:

shrikedb-cli \
  --grpc-addr http://127.0.0.1:50251 \
  --http-addr http://127.0.0.1:8182 \
  --admin-addr http://127.0.0.1:9190 \
  --database YOUR_DATABASE_ID

Or through the server binary:

shrikedb --cli \
  --grpc-addr http://127.0.0.1:50251 \
  --http-addr http://127.0.0.1:8182 \
  --admin-addr http://127.0.0.1:9190

Common startup options:

Option Use

--grpc-addr

gRPC endpoint used for query execution.

--http-addr

HTTP endpoint used for database discovery and REST metadata.

--admin-addr

Admin endpoint used for health and metrics.

--database or --db

Initial logical database selector.

--namespace

Initial namespace metadata for commands that support it.

--token

Bearer token for authenticated requests.

--api-key

API key value for CLI client metadata.

--tenant-id, --subject-id

Tenant and subject metadata for authenticated or development contexts.

--limit

Default row limit for query commands.

--format table|json|ndjson

Output format for query results.

--debug

Show additional redacted transport detail for failed commands.

Shell Commands

The shell help is generated from the same command registry the shell uses for dispatch. Inside the shell, run help or help cypher.

Command What it does

status

Checks /api/v1/health, then falls back to admin /health.

doctor

Runs endpoint, database, auth, and output checks without printing secrets.

connect grpc|http|admin <addr>

Changes endpoints for the current shell session.

databases

Lists logical databases from /api/v1/databases.

open database <id>

Selects the database sent as x-shrikedb-database on later requests.

namespace <name>

Sets x-shrikedb-namespace for commands that use namespace metadata.

sources

Lists database-scoped connector sources.

sources add <source.json>

Registers a connector source definition.

sources run <id>

Runs one connector source immediately through the server.

schedules

Lists connector polls, triggers, and maintenance schedules.

import connector …​

Loads a source into the selected database with a mapping file and optional checkpointing.

cypher <query>

Runs a Cypher statement through gRPC and prints a table or JSON.

sparql <query>

Runs a SPARQL statement through gRPC.

query cypher <query>

Runs an explicit Cypher query through the native gRPC query API.

query sparql <query>

Runs an explicit SPARQL query through the native gRPC query API.

query direct <cypher|sparql> <query>

Runs the REST direct-query inspection endpoint. Use this only when you intentionally want a direct raw-query mode.

kv get <subject_uid> <key_uid>

Reads a public key-value entry.

kv put <subject_uid> <key_uid> <value> [schema=<id>]

Writes a public key-value entry. This is an explicit mutation command.

graph scan [subject] [predicate] [object]

Scans triples by subject/predicate/object pattern. Omitted terms become variables.

graph neighbors <uid> [predicate=<p>] [direction=out|in|both]

Lists graph neighbors for one node.

graph insert <source_uid> <target_uid> [schema=<id>] [edge_type=<id>] [payload=<text>]

Inserts one graph block through the public graph ingestion API. This is an explicit mutation command.

vector insert <index> <entity_uid> <[f32,…​]>

Writes one vector to a named vector index.

vector search <index> <[f32,…​]> [k=10]

Runs vector nearest-neighbor search.

analytics <pagerank|wcc|degree|closeness|betweenness> [key=value…​]

Generates and runs an explicit GDS-style graph analytics stream query.

path <dijkstra|astar|yen|bellman-ford|apsp> key=value…​

Generates and runs an explicit GDS-style weighted-path stream query.

semantic capabilities

Shows semantic compiler capabilities through the REST semantic surface.

semantic catalog

Lists visible semantic profiles for the selected database.

semantic reason <profile> <question>

Asks the semantic reasoner to turn a natural-language question into candidate typed intents.

semantic compile|explain|execute <profile> <intent-json|@file|→

Compiles, explains, or executes a typed SemanticQueryIntent JSON payload.

semantic intent-template key=value…​

Creates a small typed intent request body for common retrieve, aggregate, and rank workflows.

mcp tools

Lists MCP tools advertised by the server.

mcp call <tool> --json <file|→

Calls a documented MCP tool with JSON from a file, stdin, inline JSON, or simple key=value scalars.

workflow start|get|probe|answer|advance|refine|fork|join|stages|list

Manages semantic workflow and conversation state through the same MCP tools used by agent clients.

set <key> <value>

Changes session settings such as limit, format, endpoints, credentials, database, or namespace.

show config

Shows shell state with credentials redacted.

explain-error

Explains the last failed command with a concise hint and redacted detail when debug mode is enabled.

metrics [filter]

Fetches admin /metrics and optionally filters text.

Typical Shell Flow

status
doctor
databases
open database tmsis_medicaid_validation
set limit 25
set format table
cypher MATCH (n) RETURN count(n) AS node_count
query sparql SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5
graph neighbors 1001 direction=both limit=10

Long Cypher or SPARQL-style inputs can be entered over multiple lines. Terminate query input with ; when the shell is waiting for continuation.

For JSON output:

set format json
cypher MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 5

For line-oriented automation:

set format ndjson
query cypher MATCH (n) RETURN n LIMIT 3

Analytics helpers are shortcuts for explicit Cypher procedure calls. For example:

analytics pagerank relationshipTypes=tmsis:hasProvider topK=10
path dijkstra sourceNode=1 targetNode=50 relationshipTypes=ROAD relationshipWeightProperty=cost

Semantic And MCP Commands

Semantic execution is typed by design. Natural-language text is accepted by semantic reason, which returns candidate intents and diagnostics. Compile, explain, and execute expect SemanticQueryIntent JSON rather than raw hidden Cypher.

semantic capabilities
semantic catalog
semantic reason tmsis_medicaid_provider_spending \
  Which providers have the highest paid amount for T1019 in July 2024?

For compile, explain, and execute, put the intent in a file:

{
  "goal": "aggregate",
  "concepts": [
    { "concept": "Provider", "binding": "provider" },
    { "concept": "Procedure", "binding": "procedure" }
  ],
  "output": {
    "fields": [
      { "binding": "provider" },
      { "binding": "procedure" }
    ]
  },
  "safety": { "limit": 25 }
}

Then run:

semantic explain tmsis_medicaid_provider_spending @intent.json
semantic execute tmsis_medicaid_provider_spending @intent.json

To create a starter JSON body:

semantic intent-template \
  profile=tmsis_medicaid_provider_spending \
  goal=aggregate \
  concepts=Provider:provider,Procedure:procedure \
  fields=provider,procedure \
  group_by=provider \
  measure_function=sum \
  measure_binding=claim \
  measure_field=paid_amount \
  measure_alias=total_paid \
  limit=25

The generic MCP escape hatch is useful when a tool does not yet have a friendly wrapper:

mcp tools
mcp call semantic_execute --json execute-request.json
mcp call semantic_catalog

Workflow commands are thin wrappers around semantic MCP tools:

workflow start profile=tmsis_medicaid_provider_spending \
  Find provider spending concentration patterns
workflow list profile=tmsis_medicaid_provider_spending
workflow stages <workflow-id>
workflow refine <workflow-id> narrow to July 2024 T1019 providers

The profile IDs, concepts, measures, and workflow IDs in these semantic examples belong to an example healthcare dataset. Replace them with entries from semantic catalog for your selected database; they are not installed automatically.

Connector Imports

The interactive shell can register and run connector-backed imports. The selected database comes from open database …​ or the --database startup option.

open database demo_claims

import connector csv claims \
  path=/data/claims.csv \
  mapping=/data/claims_mapping.json \
  checkpoint=claims-2024 \
  ensure_schema=true

Supported connector kinds in the shell command are:

  • csv

  • tsv

  • jsonl

  • http_json

  • parquet

The mapping file must already exist and describe your source columns using the connector’s schema, nodes, and edges sections. The example paths are placeholders for reviewed files from your deployment. For a complete small-file workflow without a custom connector mapping, use Import a dataset.

Checkpointing is database-scoped by default. Use checkpoint=off for a one-time reload, or give a checkpoint name when two imports use the same source with different cursors.

Operational Onboarding CLI

The server binary has a second, script-friendly CLI for onboarding endpoints. It posts JSON to the running server and prints pretty JSON responses.

Inspect a source:

shrikedb \
  --server http://127.0.0.1:8182 \
  --db demo_claims \
  onboard inspect \
  --input /data/claims.csv \
  --format csv \
  --sample-rows 50

Load a source with an optional reviewed plan:

shrikedb \
  --server http://127.0.0.1:8182 \
  --db demo_claims \
  onboard load \
  --input /data/claims.csv \
  --format csv \
  --plan /data/claims_load_plan.json \
  --graph-namespace claims \
  --row-limit 100000

Import an ontology:

shrikedb \
  --server http://127.0.0.1:8182 \
  --db cyber_demo \
  ontology import \
  --input /data/d3fend.ttl \
  --format turtle \
  --graph-namespace d3fend \
  --materialize

Run a small demo load/import/validate sequence:

shrikedb \
  --server http://127.0.0.1:8182 \
  --db cyber_demo \
  onboard demo \
  --dataset /data/lsqb.parquet \
  --ontology /data/d3fend.ttl \
  --questions /data/demo_questions.json \
  --materialize

Authentication Notes

For direct identity-service calls, use the official multi-tenant headers:

authorization: Bearer <JWT>
x-shrikedb-api-key: <key>

The interactive shell exposes session knobs named token, api_key, tenant_id, and subject_id. Use show config to confirm the shell state; credential values are redacted.

Troubleshooting

Symptom Check

status cannot reach the server

Confirm --http-addr and --admin-addr; the guide examples use 8182 and 9190.

databases is empty

The server may have no discovered logical databases yet, or the selected config uses a different data directory.

A query runs against the wrong database

Run show config, then open database <id>.

Connector import resumes unexpectedly

Use a different checkpoint=<name> or checkpoint=off.

Authenticated requests fail

Confirm the server was built with multi-tenant, the token/API key is active, and the user has the required scope and mode.