CLI Reference¶

The indentiagraph command-line interface provides a complete set of tools for running, querying, managing, and administering IndentiaDB instances. Every subcommand supports both human-readable text output and machine-parseable JSON output via the --format json global flag, making the CLI equally suited for interactive use and CI/CD pipelines.

Installation¶

The CLI is included in every IndentiaDB distribution. After installing IndentiaDB, verify the CLI is available:

indentiagraph --version

The binary is statically linked and has no runtime dependencies beyond libc.

Global Flags¶

Every subcommand inherits these global flags:

Flag	Short	Default	Description
`--verbose`	`-v`	`false`	Enable debug-level logging to stderr
`--format`	`-f`	`text`	Output format: `text` (human-readable) or `json` (machine-parseable)

# JSON output for scripting
indentiagraph --format json query sparql --query "SELECT * WHERE { ?s ?p ?o } LIMIT 5"

# Verbose debug output
indentiagraph -v serve --config config.toml

`indentiagraph serve`¶

Start the IndentiaDB server. This launches the main HTTP server (SPARQL, REST, GraphQL, WebSocket), the Elasticsearch-compatible API on port 9200, and optionally joins a Raft cluster.

Usage¶

indentiagraph serve [OPTIONS]

Options¶

Option	Short	Default	Description
`--config`	`-c`	Auto-detected	Path to TOML configuration file
`--port`	`-p`	`7001`	HTTP server port (overrides config)
`--bind-address`	`-b`	`0.0.0.0`	HTTP server bind address (overrides config)
`--es-port`		`9200`	Elasticsearch-compatible API port (overrides config)
`--es-bind-address`		`0.0.0.0`	Elasticsearch API bind address (overrides config)
`--index`	`-i`		Path to index files (overrides config)
`--node-id`			Node ID for Raft cluster mode (overrides config)
`--seed-nodes`			Comma-separated seed node addresses for cluster discovery

Examples¶

Start a development server with default settings:

indentiagraph serve

Start with a specific configuration file and port override:

indentiagraph serve --config /etc/indentiadb/config.toml --port 8080

Start a cluster node with seed discovery:

indentiagraph serve \
  --config config.toml \
  --node-id 2 \
  --seed-nodes "node-1.internal:7002,node-3.internal:7002"

Configuration File Auto-Detection

When --config is not specified, IndentiaDB searches for config.toml or indentiagraph.toml in the current working directory. Use the INDENTIADB_CONFIG environment variable to set a default path without passing --config on every invocation.

`indentiagraph query`¶

Execute queries against a running IndentiaDB instance. The query command has subcommands for each query protocol: SPARQL, SPARQL UPDATE, Graph Store Protocol, GraphQL, SHACL validation, and GeoSPARQL evaluation.

`query sparql` -- Execute SPARQL SELECT/CONSTRUCT/ASK/DESCRIBE¶

indentiagraph query sparql [OPTIONS]

Option	Default	Description
`--query`		SPARQL query text (inline)
`--file`		Read query from file (use `-` for stdin)
`--method`	`post`	HTTP method: `get` or `post`
`--format`		Request specific result format (e.g. `json`, `xml`, `csv`)
`--consistency`		Request consistency level (e.g. `strong`)
`--no-streaming`	`false`	Disable server-side streaming
`--accept`		Override the HTTP Accept header
`--ndjson`	`false`	Request NDJSON streaming response
`--show-status`	`false`	Print HTTP status line
`--include-headers`	`false`	Print HTTP response headers
`--allow-http-error`	`false`	Do not exit with error on non-2xx status

Examples¶

Inline query:

indentiagraph query sparql \
  --endpoint http://localhost:7001 \
  --query "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10"

Query from file:

indentiagraph query sparql \
  --profile prod \
  --file queries/find-employees.rq

Query from stdin (pipe from another program):

cat query.rq | indentiagraph query sparql --profile prod --file -

Request CSV output:

indentiagraph query sparql \
  --endpoint http://localhost:7001 \
  --query "SELECT ?name ?age WHERE { ?p foaf:name ?name ; foaf:age ?age }" \
  --accept "text/csv"

NDJSON streaming for large result sets:

indentiagraph query sparql \
  --profile prod \
  --query "SELECT * WHERE { ?s ?p ?o }" \
  --ndjson

`query update` -- Execute SPARQL UPDATE¶

indentiagraph query update [OPTIONS]

Option	Default	Description
`--update`		SPARQL UPDATE text (inline)
`--file`		Read update from file (use `-` for stdin)

Examples¶

Insert triples:

indentiagraph query update \
  --profile prod \
  --update "INSERT DATA { <http://example.org/alice> <http://xmlns.com/foaf/0.1/name> 'Alice' . }"

Load from file:

indentiagraph query update --profile prod --file migrations/add-schema.ru

`query graph` -- Graph Store Protocol¶

indentiagraph query graph [OPTIONS]

Option	Default	Description
`--endpoint-path`	`data`	Graph Store endpoint: `data` or `graph-store`
`--method`		HTTP method: `get`, `head`, `put`, `post`, `patch`, `delete`
`--graph`		Named graph IRI
`--default-graph`	`false`	Target the default graph
`--data`		RDF payload text
`--file`		Read RDF payload from file
`--content-type`	`text/turtle`	RDF serialization format

Examples¶

Retrieve a named graph as Turtle:

indentiagraph query graph \
  --profile prod \
  --method get \
  --graph "http://example.org/employees"

Upload Turtle data to a named graph:

indentiagraph query graph \
  --profile prod \
  --method put \
  --graph "http://example.org/employees" \
  --file data/employees.ttl \
  --content-type "text/turtle"

Delete a named graph:

indentiagraph query graph \
  --profile prod \
  --method delete \
  --graph "http://example.org/old-data"

`query graphql` -- Execute GraphQL Queries¶

indentiagraph query graphql [OPTIONS]

Option	Default	Description
`--query`		GraphQL query text
`--file`		Read query from file
`--variables`		Variables as inline JSON string
`--variables-file`		Read variables from JSON file
`--operation-name`		GraphQL operation name

Example¶

indentiagraph query graphql \
  --profile prod \
  --query '{ persons(limit: 5) { name email } }' \
  --variables '{"limit": 5}'

`query shacl` -- SHACL Validation¶

indentiagraph query shacl [OPTIONS]

Option	Default	Description
`--shapes`		SHACL shapes text
`--file`		Read shapes from file
`--format`		Shapes format: `turtle`, `jsonld`, `ntriples`, `rdfxml`
`--graph-iri`		Specific graph IRI to validate
`--timeout-ms`		Validation timeout in milliseconds
`--include-warnings`		Include warning-level violations
`--include-infos`		Include info-level violations
`--enable-sparql-constraints`		Enable SHACL-SPARQL constraints
`--enable-rules`		Enable SHACL rules inference

Example¶

indentiagraph query shacl \
  --profile prod \
  --file shapes/person-shape.ttl \
  --graph-iri "http://example.org/employees" \
  --include-warnings true

`query geo` -- GeoSPARQL Function Evaluation¶

indentiagraph query geo [OPTIONS]

Option	Default	Description
`--function`		GeoSPARQL function IRI or short name
`--arg`		Argument as JSON term object (repeatable)
`--args-file`		Read arguments from JSON array file

Example¶

indentiagraph query geo \
  --profile prod \
  --function "geof:distance" \
  --arg '{"type": "literal", "value": "POINT(4.9 52.3)", "datatype": "geo:wktLiteral"}' \
  --arg '{"type": "literal", "value": "POINT(5.1 52.1)", "datatype": "geo:wktLiteral"}'

`indentiagraph admin`¶

Call the server's management API — cluster state and health, index and tenant topology, shard snapshots, the base-index lifecycle, projection repair, exports, governance, licenses, and alerts — with the same connection profiles and credentials as query. Server-side authorization and production restrictions apply unchanged.

indentiagraph admin list                     # catalog of named operations
indentiagraph admin run <OPERATION> [OPTIONS]
indentiagraph admin request <METHOD> <PATH> [OPTIONS]

Subcommand	Description
`list`	Print every named operation with its HTTP method, path, and required path arguments (`--format json` for scripts)
`run`	Execute a named operation from `admin list`; request bodies follow the server API
`request`	Call any route on the configured endpoint by method (`GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`) and endpoint-relative path — for extension APIs, optional services, or the Elasticsearch API on port 9200

Options¶

run and request accept the connection flags plus:

Option	Default	Description
`--arg NAME=VALUE`		Path argument for `run`, e.g. `--arg index=corpus` (repeatable)
`--param NAME=VALUE`		URL-encoded query parameter; repeated parameters are preserved
`--header NAME=VALUE`		Additional application header. Credentials come from the connection options, not from headers.
`--json`		Inline JSON request body
`--file`		Request body file; `-` reads stdin
`--content-type`	`application/json`	Body media type, e.g. `application/sparql-update`
`--mutation-id`		Stable UUIDv7 sent as `x-indentia-mutation-id`, for retrying a mutation safely
`--output`	stdout	Write the response to a new file (owner-only permissions on Unix; an existing file is never overwritten)
`--ca-cert`		Additional trusted CA certificate in PEM format (repeatable)
`--client-identity`		PEM client certificate chain and private key for mutual TLS (HTTPS endpoints only)

Examples¶

indentiagraph admin run cluster-state --profile prod
indentiagraph admin run cluster-health --endpoint https://node-1.example.com:7001 \
  --ca-cert ca.pem --client-identity client.pem
indentiagraph admin run index-create --profile prod --file index.json
indentiagraph admin run tenant-route --profile prod --param tenant=acme
indentiagraph admin run shard-snapshot --profile prod --arg group_no=1
indentiagraph admin run force-snapshot --profile prod --json '{"target":"meta"}'
indentiagraph admin run base-index-status --profile prod
indentiagraph admin run export-nquads --profile prod --output export.nq
indentiagraph admin request GET /_cluster/health --endpoint https://search.example.com:9200

Responses stream to stdout or to the --output file, so large exports never need a response-sized buffer; only a zero exit status establishes a completed export. Any non-2xx status — including a redirect — fails the command: management requests are sent once and never replayed at a redirect target, so point the command at the leader explicitly when an operation requires it. Prefer IG_REMOTE_BEARER_TOKEN or IG_REMOTE_PASSWORD over command-line credentials.

Management area	Named operations
Health, readiness, metrics	`health`, `ready`, `live`, `metrics`
Cluster state and health	`cluster-state`, `cluster-health`
Index lifecycle, allocation, shard topology	`index-create`, `index-delete`, `index-allocate`, `rebalance`, `shard-start`
Tenant mapping, routing, counts	`tenant-map`, `tenant-route`, `tenant-count`, `index-count`
Cluster data queries	`tenant-update`, `index-query`, `index-join-query`
Nodes and metadata replicas	`node-register`, `node-drain`, `meta-replicas`
Snapshots	`force-snapshot`, `shard-snapshot`
Base-index lifecycle	`base-index-status`, `base-index-begin`, `base-index-prepare`, `base-index-prepared`, `base-index-attach`, `base-index-abort`
Projection repair and export	`projection-resume`, `export-nquads`
Governance and ontology	`ontology-activate`, `ontology-migration-`, `tenant-provision`, `tenant-resolve`, `governed-`, `outbox-*`
Streams, licenses, alerts	`stream-status`, `license-`, `alerts`, `alert-`

`indentiagraph validate`¶

Validate the integrity of IndentiaDB index files. This checks permutation index files (SPO, SOP, PSO, POS, OSP, OPS), vocabulary files, block metadata structure, and performs sample decompression tests to detect corruption.

Usage¶

indentiagraph validate --index <PATH> [OPTIONS]

Options¶

Option	Short	Default	Description
`--index`	`-i`	(required)	Path to index files (base path without extension)
`--sample-size`	`-s`	`5`	Number of blocks to sample per permutation for decompression testing

Examples¶

Validate with default sampling:

indentiagraph validate --index /var/lib/indentiadb/data/index

Deep validation with more samples:

indentiagraph validate --index /var/lib/indentiadb/data/index --sample-size 50

JSON output for CI pipelines:

indentiagraph --format json validate --index /var/lib/indentiadb/data/index

Validation Does Not Require a Running Server

The validate command reads index files directly from disk. It can be run while the server is stopped, making it suitable for pre-start health checks and post-backup verification.

`indentiagraph backup`¶

Create, list, verify, restore, prune, and replicate backups. Backups can cover the full database or specific components (indices, tables, graphs, or arbitrary paths). Each backup produces an Ed25519-signed manifest.json with SHA-256 checksums for every file. See Backup & Disaster Recovery for the operational workflow.

`backup create`¶

indentiagraph backup create --source <DIR> [OPTIONS]

Option	Default	Description
`--source`	(required)	Source root directory
`--source-is-consistent-snapshot`	`false`	Attest that the source is an offline data directory or a storage-level point-in-time snapshot
`--snapshot-provider`	`IG_BACKUP_SNAPSHOT_PROVIDER`	External executable that creates/releases a consistent snapshot around the copy
`--repository`	`./backups`	Backup repository directory
`--id`	Timestamp-based	Backup identifier
`--index`		Add index component as `NAME=PATH` (repeatable)
`--table`		Add table component as `NAME=PATH` (repeatable)
`--graph`		Add graph component as `NAME=PATH` (repeatable)
`--path`		Add custom path component (repeatable)
`--dry-run`	`false`	Only print what would be backed up

Consistency is mandatory

backup create is a file-level copy of a data directory — it does not snapshot a live database itself. It refuses to run without either --source-is-consistent-snapshot (all writers stopped, or the source is a storage-level snapshot) or a --snapshot-provider. Under IG_PRODUCTION=true a snapshot provider is required.

Examples¶

Full database backup:

indentiagraph backup create \
  --source /var/lib/indentiadb/data \
  --source-is-consistent-snapshot \
  --repository /mnt/backups/indentiadb

Selective backup of specific components:

indentiagraph backup create \
  --source /var/lib/indentiadb/data \
  --source-is-consistent-snapshot \
  --repository /mnt/backups/indentiadb \
  --id "pre-migration-2026-03" \
  --index "spo=permutations/spo" \
  --index "pos=permutations/pos" \
  --graph "employees=graphs/employees"

Dry run to preview what will be backed up:

indentiagraph backup create \
  --source /var/lib/indentiadb/data \
  --dry-run

`backup list`¶

indentiagraph backup list --repository /mnt/backups/indentiadb

`backup show`¶

indentiagraph backup show \
  --repository /mnt/backups/indentiadb \
  --id "bk-1711929600"

`backup verify`¶

Verify SHA-256 checksums and file sizes for all files in a backup:

indentiagraph backup verify \
  --repository /mnt/backups/indentiadb \
  --id "bk-1711929600"

Verify After Every Backup

Run backup verify immediately after backup create and periodically thereafter to detect bit rot on the backup storage medium. Exit code 0 means all checksums match.

`backup restore`¶

indentiagraph backup restore \
  --repository /mnt/backups/indentiadb \
  --id "bk-1711929600" \
  --destination /var/lib/indentiadb/data-restored

The destination must be a new, non-existent directory: restore verifies every checksum, stages the files, and publishes the directory with one rename. --overwrite is kept only for compatibility — an in-place restore is refused because it cannot be atomic. Switch the service (or PVC mount) to the restored directory afterwards.

Selective restore (only specific components):

indentiagraph backup restore \
  --repository /mnt/backups/indentiadb \
  --id "bk-1711929600" \
  --destination /var/lib/indentiadb/data-restored \
  --index spo \
  --index pos

Dry-run restore:

indentiagraph backup restore \
  --repository /mnt/backups/indentiadb \
  --id "bk-1711929600" \
  --destination /tmp/restore-test \
  --dry-run

`backup prune`¶

Remove old backups, keeping only the newest N:

indentiagraph backup prune \
  --repository /mnt/backups/indentiadb \
  --keep 5

Preview what would be removed:

indentiagraph backup prune \
  --repository /mnt/backups/indentiadb \
  --keep 5 \
  --dry-run

`backup push` / `backup pull`¶

Replicate a backup to (or fetch it from) S3-compatible object storage for off-node disaster recovery. Configure the endpoint via IG_S3_ENDPOINT, IG_S3_BUCKET, IG_S3_ACCESS_KEY, and IG_S3_SECRET_KEY:

indentiagraph backup push \
  --repository /mnt/backups/indentiadb \
  --id "bk-1752130000"

indentiagraph backup pull \
  --repository /restore/backups \
  --id "bk-1752130000"

Option	Default	Description
`--id`	(required)	Backup identifier
`--repository`	`./backups`	Local backup repository
`--prefix`	`backups`	Object key prefix in the bucket

Pushes verify the backup against its manifest first, use resumable multipart uploads, and commit the manifest last with a conditional write so backup IDs are immutable in the bucket. Pulls download to a staging directory, re-verify every checksum, and publish atomically. See Backup & DR for the full S3 variable reference.

`backup sign-manifest`¶

Re-sign an existing backup manifest in place — the migration exit for backups created before manifest signing was enabled:

indentiagraph backup sign-manifest \
  --repository /mnt/backups/indentiadb \
  --id "bk-1711929600"

Every payload checksum is re-verified before signing, so a corrupt backup is never blessed with a signature. Requires IG_BACKUP_MANIFEST_SIGNING_KEY_FILE and IG_BACKUP_MANIFEST_SIGNING_KEY_ID.

`indentiagraph backup-set`¶

Authenticate and restore HA Backup Sets — authenticated Raft snapshot archives exported by a production cluster. Every command that reads an archive requires the manifest SHA-256 obtained through an independent, trusted channel. See HA Backup Sets for the export side and the full restore procedure.

Cluster Backup Set¶

A cluster Backup Set (cluster-set.igcs) covers the metadata group and every allocated shard group and is restored on all nodes as one unit.

Subcommand	Options	Description
`cluster-inspect`	`--archive`, `--expected-manifest-sha256`	Authenticate the archive and print non-secret metadata
`cluster-prepare-one`	`--archive`, `--plan`, `--node-id`, `--as-node-id`, `--data-root`, `--receipt-output`	Prepare every Raft root one node owns (metadata and shard groups) under an empty `--data-root`, and write a receipt. `--plan` is the second-channel restore plan JSON; `--as-node-id` prepares the roots of that attested member from a maintenance pod (the node must then boot with that ID).
`cluster-verify-receipts`	`--archive`, `--expected-manifest-sha256`, `--receipt` (repeatable, required)	Enforce the whole-cluster invariant: succeeds only if every member of every group presented a receipt from the same archive and restore epoch, printing `IG_CLUSTER_BACKUP_VERIFY_RECEIPTS_OK`

indentiagraph backup-set cluster-inspect \
  --archive cluster-set.igcs --expected-manifest-sha256 <pin>

# On every node, with that node's ID
indentiagraph backup-set cluster-prepare-one \
  --archive cluster-set.igcs --plan plan.json \
  --node-id 1 --data-root /data \
  --receipt-output /data/cluster-restore-receipt.json

# Once, with all receipts — start no node before this succeeds
indentiagraph backup-set cluster-verify-receipts \
  --archive cluster-set.igcs --expected-manifest-sha256 <pin> \
  --receipt r1.json --receipt r2.json --receipt r3.json

Fixed three-node Backup Set¶

A fixed three-node Backup Set (backup-set.ig3) restores into three stopped, empty voter roots with node IDs 1, 2, and 3.

Subcommand	Options	Description
`ensure-target-root`	`--data-root`, `--node-id`	Create or validate the one fixed voter root (`raft/node-<id>`) under an existing data mount
`pull-archive`	`--object-key`, `--archive-output`, `--expected-archive-sha256`, `--expected-manifest-sha256`	Pull one content-pinned archive from object storage configured through `IG_S3_*`
`inspect`	`--archive`, `--expected-manifest-sha256`	Authenticate an archive and print non-secret recovery metadata
`preflight`	`--archive`, `--plan`, `--node-id`, `--raft-root`	Validate archive, pins, keys, target, and bootstrap preconditions without writing
`prepare-one`	`--archive`, `--plan`, `--node-id`, `--raft-root`, `--receipt-output`	Idempotently prepare one stopped voter root and write a receipt
`publish-receipt`	`--receipt`, `--namespace`, `--config-map`, `--cluster-name`, `--expected-cluster-uid`, `--expected-cluster-uuid`, `--transaction-id`, `--restore-epoch`, `--node-id`, `--api-ca-file`, `--service-account-token-file`, `--wait-timeout-secs`	Publish a verified receipt into its pre-created, immutable Kubernetes ConfigMap
`verify-startup`	`--plan`, `--node-id`, `--raft-root`, `--pod-uid` (`POD_UID`), `--expected-release-file-sha256` (`IG_BACKUP_SET_EXPECTED_RELEASE_FILE_SHA256`)	Verify the released startup material for one prepared voter

`indentiagraph pitr`¶

List, restore, and prune the continuous point-in-time-recovery archive in S3-compatible object storage. Commands use the IG_S3_* connection variables (HTTPS is required under IG_PRODUCTION) and the IG_PITR_S3_PREFIX key prefix. --cluster <uuid> selects the archive; it defaults to the stable IG_CLUSTER_ID, and the commands refuse to guess when no stable identity is configured. See Point-in-Time Recovery.

Subcommand	Options	Description
`list`	`--timeline`, `--cluster`	List archived WAL timelines and Raft snapshot groups, or one timeline's artifacts
`restore-wal`	`--dest` (required), `--timeline`, `--upto-gen` \| `--upto-time`, `--cluster`	Download and verify a WAL restore chain into a fresh directory that becomes a bootable `IG_RDF_WAL_DIR`. `--upto-time` takes RFC 3339 or epoch milliseconds and resolves to the sealed-segment boundary; omit both limits for the latest state. `--timeline` defaults to the archive's single timeline.
`restore-raft`	`--group` (required), `--node-id` (required), `--data-root` (required), `--snapshot-id` \| `--latest` \| `--upto-time`, `--cluster`	Seed one node's Raft state for a group (`meta`, or a shard group number such as `7` / `group-7`) from an archived snapshot. Run once per group per voter.
`prune`	`--older-than` (required), `--dry-run`, `--cluster`	Delete artifacts older than a window (`30d`, `12h`, `90m`, `3600s`; a bare number means days) while preserving every chain a retained restore point needs

indentiagraph pitr list
indentiagraph pitr restore-wal --dest /restore/rdf-wal --upto-time 2026-09-03T02:00:00Z
indentiagraph pitr restore-raft --group meta --node-id 1 --data-root /data --latest
indentiagraph pitr prune --older-than 30d --dry-run

`indentiagraph shard-wal`¶

Offline exit ramp for retired legacy per-shard WALs. A server refuses to boot while IG_SHARD_DATA_DIR holds record-bearing shard-N.wal files; export them to N-Quads, re-ingest through the normal write path, and archive the files so the next boot passes. See Cluster Boot Checks.

indentiagraph shard-wal export --dir <LEGACY_SHARD_DIR> (--shard <N> | --all) --out <FILE.nq> [OPTIONS]

Option	Default	Description
`--dir`	(required)	The legacy shard-WAL directory (the old `IG_SHARD_DATA_DIR`)
`--shard`		Export a single shard number
`--all`	`false`	Export every legacy shard WAL in `--dir`
`--out`	(required)	Output N-Quads file, created only after every selected WAL decoded cleanly
`--archive`	`false`	After the export file is durably written, rename each exported WAL to `.wal.retired` so the boot check passes
`--allow-torn-tail`	`false`	Accept, with a warning, a torn trailing record instead of refusing

indentiagraph shard-wal export --dir /data/shards --all --out shards.nq --archive

`indentiagraph auth`¶

Manage authentication profiles and OIDC tokens. The CLI stores connection profiles in ~/.config/indentiagraph/profiles.toml and cached tokens in ~/.config/indentiagraph/tokens.json (file permissions 0600).

`auth login` -- OIDC Device Flow Login¶

Authenticate using the OIDC device authorization flow. The CLI displays a URL and code; open the URL in a browser to complete authentication.

indentiagraph auth login \
  --profile prod \
  --endpoint https://indentiadb.example.com:7001 \
  --issuer https://auth.example.com/realms/indentiadb \
  --client-id indentiadb-cli \
  --scope "openid profile" \
  --default

Option	Default	Description
`--profile`	(required)	Profile name to create or update
`--endpoint`	(required)	IndentiaDB server endpoint
`--issuer`	(required)	OIDC issuer URL
`--client-id`	(required)	OIDC client ID
`--scope`		OAuth scopes
`--default`	`false`	Set as default profile
`--insecure`	`false`	Skip TLS certificate verification
`--timeout-secs`	`30`	HTTP request timeout

`auth token` -- Inspect or Refresh Tokens¶

# Show token info (masked by default)
indentiagraph auth token --profile prod

# Show full token values (use with caution)
indentiagraph auth token --profile prod --show-full

# Force a token refresh
indentiagraph auth token --profile prod --refresh

`auth logout` -- Remove Cached Tokens¶

indentiagraph auth logout --profile prod

`auth profiles list`¶

indentiagraph auth profiles list

Output:

* prod -> https://indentiadb.example.com:7001
  dev  -> http://localhost:7001

The * marker indicates the default profile.

`auth profiles show`¶

indentiagraph auth profiles show --profile prod

`auth profiles set-default`¶

indentiagraph auth profiles set-default --profile dev

Connection Profiles¶

Connection profiles store endpoint URLs and authentication settings so you do not have to pass --endpoint, --bearer-token, or credentials on every command invocation.

Profile Configuration File¶

Profiles are stored in ~/.config/indentiagraph/profiles.toml:

default_profile = "prod"

[profiles.prod]
endpoint = "https://indentiadb.example.com:7001"
auth_mode = "oidc"

[profiles.prod.oidc]
issuer = "https://auth.example.com/realms/indentiadb"
client_id = "indentiadb-cli"
scope = "openid profile"
token_endpoint = "https://auth.example.com/realms/indentiadb/protocol/openid-connect/token"

[profiles.dev]
endpoint = "http://localhost:7001"
auth_mode = "basic"
username = "root"
password = "root"

[profiles.staging]
endpoint = "https://staging.indentiadb.internal:7001"
auth_mode = "bearer"
bearer_token = "eyJhbGciOi..."

Authentication Modes¶

Mode	Description	When to Use
`oidc`	OIDC device flow with automatic token refresh	Production environments with an identity provider
`bearer`	Static bearer token	Service accounts, short-lived scripts
`basic`	HTTP Basic Auth (username + password)	Development, local testing

Connection Flags¶

Any query, admin, or auth command accepts these connection flags, which override profile settings:

Flag	Description
`--profile`	Select a named profile
`--endpoint`	Override the server endpoint URL
`--bearer-token`	Override with a specific bearer token (env: `IG_REMOTE_BEARER_TOKEN` — preferred, keeps the token out of process listings and shell history)
`--username`	Override Basic Auth username (env: `IG_REMOTE_USERNAME`)
`--password`	Override Basic Auth password (env: `IG_REMOTE_PASSWORD` — preferred)
`--insecure`	Skip TLS certificate verification
`--timeout-secs`	HTTP request timeout in seconds (default: 30)
`--no-refresh`	Disable automatic OIDC token refresh

Token Auto-Refresh

When using an OIDC profile, the CLI automatically refreshes expired access tokens using the stored refresh token before sending a request. If the refresh fails, the CLI returns a 401 error and you must re-authenticate with auth login. Use --no-refresh to disable this behavior.

`indentiagraph generate-config`¶

Generate a sample TOML configuration file with sensible defaults and inline comments:

# Print to stdout
indentiagraph generate-config

# Write to file
indentiagraph generate-config --output /etc/indentiadb/config.toml

# Without comments (minimal)
indentiagraph generate-config --output config.toml --no-comments

Environment Variables¶

The CLI respects the same environment variables as the server. The most relevant for CLI usage:

Variable	Description
`INDENTIADB_CONFIG`	Default path to configuration file
`INDENTIADB_PORT`	Default server port
`INDENTIADB_BIND_ADDRESS`	Default bind address
`SURREAL_ENDPOINT`	SurrealDB WebSocket endpoint
`SURREAL_USERNAME`	SurrealDB username
`SURREAL_PASSWORD`	SurrealDB password
`LOG_LEVEL`	Log level: `trace`, `debug`, `info`, `warn`, `error`
`LOG_FORMAT`	Log format: `json` or `text`

See Configuration Reference for the complete list.

Scripting and Automation¶

JSON Output for Pipelines¶

Use --format json to get structured output suitable for parsing with jq:

# Get backup list as JSON and extract IDs
indentiagraph --format json backup list \
  --repository /mnt/backups | jq '.[].id'

# Check backup verification result
RESULT=$(indentiagraph --format json backup verify \
  --repository /mnt/backups --id "bk-latest")
echo "$RESULT" | jq '.ok'

Cron Job: Nightly Backup with Pruning¶

#!/bin/bash
set -euo pipefail

REPO="/mnt/backups/indentiadb"
SOURCE="/var/lib/indentiadb/data"
# Executable that creates and releases a storage-level snapshot of $SOURCE
SNAPSHOT_PROVIDER="/usr/local/bin/indentiadb-snapshot-provider"

# Create backup (refused without a consistency attestation or snapshot provider)
indentiagraph backup create \
  --source "$SOURCE" \
  --snapshot-provider "$SNAPSHOT_PROVIDER" \
  --repository "$REPO"

# Verify the latest backup
LATEST=$(indentiagraph --format json backup list --repository "$REPO" \
  | jq -r '.[0].id')
indentiagraph backup verify --repository "$REPO" --id "$LATEST"

# Keep only the 7 most recent backups
indentiagraph backup prune --repository "$REPO" --keep 7

Health Check Script¶

#!/bin/bash
# Quick health check: run a trivial SPARQL query
indentiagraph query sparql \
  --profile prod \
  --query "ASK { ?s ?p ?o }" \
  --allow-http-error \
  --show-status

Exit Codes¶

Code	Meaning
`0`	Success
`1`	General error (invalid arguments, missing files, network failure)
`1`	HTTP error response (non-2xx) unless `--allow-http-error` is set
`1`	Backup verification failed (missing or corrupt files)

Non-2xx HTTP Responses

By default, the CLI exits with code 1 when the server returns a non-2xx HTTP status. Use --allow-http-error to suppress this behavior when you want to inspect the error response body in scripts.

CLI Reference¶

Installation¶

Global Flags¶

indentiagraph serve¶

Usage¶

Options¶

Examples¶

indentiagraph query¶

query sparql -- Execute SPARQL SELECT/CONSTRUCT/ASK/DESCRIBE¶

Examples¶

query update -- Execute SPARQL UPDATE¶

Examples¶

query graph -- Graph Store Protocol¶

Examples¶

query graphql -- Execute GraphQL Queries¶

Example¶

query shacl -- SHACL Validation¶

Example¶

query geo -- GeoSPARQL Function Evaluation¶

Example¶

indentiagraph admin¶

Options¶

Examples¶

indentiagraph validate¶

Usage¶

Options¶

Examples¶

indentiagraph backup¶

backup create¶

Examples¶

backup list¶

backup show¶

backup verify¶

backup restore¶

backup prune¶

backup push / backup pull¶

backup sign-manifest¶

indentiagraph backup-set¶

Cluster Backup Set¶

Fixed three-node Backup Set¶

indentiagraph pitr¶

indentiagraph shard-wal¶

indentiagraph auth¶

auth login -- OIDC Device Flow Login¶

auth token -- Inspect or Refresh Tokens¶

auth logout -- Remove Cached Tokens¶

auth profiles list¶

auth profiles show¶

auth profiles set-default¶

Connection Profiles¶

Profile Configuration File¶

Authentication Modes¶

Connection Flags¶

indentiagraph generate-config¶

Environment Variables¶

Scripting and Automation¶

JSON Output for Pipelines¶

Cron Job: Nightly Backup with Pruning¶

Health Check Script¶

Exit Codes¶

`indentiagraph serve`¶

`indentiagraph query`¶

`query sparql` -- Execute SPARQL SELECT/CONSTRUCT/ASK/DESCRIBE¶

`query update` -- Execute SPARQL UPDATE¶

`query graph` -- Graph Store Protocol¶

`query graphql` -- Execute GraphQL Queries¶

`query shacl` -- SHACL Validation¶

`query geo` -- GeoSPARQL Function Evaluation¶

`indentiagraph admin`¶

`indentiagraph validate`¶

`indentiagraph backup`¶

`backup create`¶

`backup list`¶

`backup show`¶

`backup verify`¶

`backup restore`¶

`backup prune`¶

`backup push` / `backup pull`¶

`backup sign-manifest`¶

`indentiagraph backup-set`¶

`indentiagraph pitr`¶

`indentiagraph shard-wal`¶

`indentiagraph auth`¶

`auth login` -- OIDC Device Flow Login¶

`auth token` -- Inspect or Refresh Tokens¶

`auth logout` -- Remove Cached Tokens¶

`auth profiles list`¶

`auth profiles show`¶

`auth profiles set-default`¶

`indentiagraph generate-config`¶