Skip to content

CLI reference

Reference

The telha binary is both the server and the operator CLI: telha serve starts the engine, and every other subcommand is an operator tool. Most subcommands open the data directory directly (an exclusive RocksDB lock), so stop the server first; the exceptions are noted per command.

Global flags (RunArgs)

Every subcommand below that touches config or storage accepts these flags (flattened into the command, not a separate top-level option):

Flag Env Type Default Notes
--config <path> TELHA_CONFIG path none TOML config file. A missing file given explicitly is an error.
--data-dir <path> none path ./data Overrides data_dir.
--rest-addr <addr> none socket addr 127.0.0.1:7625 Overrides rest.addr. Port 0 binds ephemerally.
--grpc-addr <addr> none socket addr 127.0.0.1:7626 Overrides grpc.addr.
--uds-path <path> none path none Overrides grpc.uds_path (Unix only).
--log-level <filter> none string info Overrides log.level (a tracing filter directive).
--log-format <json\|pretty> none enum json Overrides log.format.

CLI flags are the highest layer of precedence: defaults → TOML file → TELHA_* env → CLI flags. See Configuration keys for the full layering rule.

Serving and inspection

telha serve

Synopsis: telha serve [RunArgs]

Starts the engine: initializes logging, installs an OS-signal shutdown hook, then runs the REST listener (gRPC and MCP listeners start alongside it when configured). Loads and validates the full config before binding anything.

Start with an explicit data dir and REST address
telha serve --data-dir ./data --rest-addr 127.0.0.1:7625

telha version

Synopsis: telha version

Prints build information and exits. No flags.

Check the build
telha version
# telha-core 0.1.0 (x86_64, rust ...)

telha check-config

Synopsis: telha check-config [RunArgs]

Loads, validates, and prints the fully resolved configuration as TOML, then exits without starting any listener. Non-fatal warnings (e.g. a Windows host with grpc.uds_path set, or clarify.enabled without grpc.token_key) print to stderr first.

Validate a config file before first start
telha check-config --config /etc/telha/telha.toml

Keys and tokens (api-key)

API keys are file-backed (hashes only at rest, in {data_dir}/api_keys.json); the server loads that file at boot, so mint keys before serve or restart afterward. Service tokens are minted on demand from grpc.token_key and are never stored; each expires after TOKEN_TTL_SECS (300 s) and is meant to be re-minted on an interval by its consumer.

Subcommand Opens data dir? Requires grpc.token_key?
api-key create yes (direct) no
api-key worker-token no yes
api-key mcp-token no yes
api-key clarify-token no yes
api-key admin-token no yes
api-key connector-token no yes

telha api-key create

Synopsis: telha api-key create --tenant <uuid> --org <uuid> [--person <uuid>] [--role <role>] [RunArgs]

Creates a key scoped to a (tenant, organization) pair and prints the plaintext once; only its hash is written to api_keys.json. Opens the data dir directly.

Flag Type Default Notes
--tenant UUID required Tenant scope.
--org UUID required Organization scope.
--person UUID none The PERSON this key answers clarifications as. Without it the key cannot answer clarifications at all.
--role string none Rights of that principal: viewer|editor|steward.
Mint a tenant key bound to an answering person
telha api-key create --tenant $TENANT --org $ORG --person $PERSON --role editor --data-dir ./data
# tk_...   <- shown once

telha api-key worker-token

Synopsis: telha api-key worker-token --worker-id <id> [RunArgs]

Mints a short-lived worker token (audience worker; accepted only by WorkerService). Requires grpc.token_key in the resolved config.

telha api-key worker-token --worker-id docling-1

telha api-key mcp-token

Synopsis: telha api-key mcp-token --tenant <uuid> --org <uuid> [RunArgs]

Mints a short-lived MCP session token (audience mcp; accepted only by the MCP listener).

telha api-key mcp-token --tenant $TENANT --org $ORG

telha api-key clarify-token

Synopsis: telha api-key clarify-token (--worker-id <id> | --tenant <uuid> --org <uuid>) [RunArgs]

Mints a short-lived clarify-bot token (audience clarify). --worker-id mints the polling identity used against WorkerService's clarify: lease fence (conflicts with --tenant/--org); --tenant + --org (required together) mint the tenant-scoped bearer token the answer endpoint accepts.

telha api-key clarify-token --worker-id clarify-bot            # poll
telha api-key clarify-token --tenant $TENANT --org $ORG         # answer

telha api-key admin-token

Synopsis: telha api-key admin-token --tenant <uuid> --org <uuid> [RunArgs]

Mints a short-lived operator admin token (audience admin) that opens the /admin/* REST surface for the named tenant. Operator-scoped only: API keys never open /admin.

telha api-key admin-token --tenant $TENANT --org $ORG

telha api-key connector-token

Synopsis: telha api-key connector-token --connector <name> --tenant <uuid> --org <uuid> [RunArgs]

Mints a short-lived connector token (audience connector), tenant-scoped and named: it leases only that tenant's sync: jobs and deletes only records in its own namespace.

telha api-key connector-token --connector sharepoint --tenant $TENANT --org $ORG

Vectors (vector)

Registry commands open the data dir directly; stop the server first.

telha vector register-model

Synopsis: telha vector register-model --name <name> --dims <n> [--normalize] [--provider-ref <ref>] [RunArgs]

Registers (or updates the metadata of) an embedding model.

Flag Type Default Notes
--name string required Wire name sent to the provider.
--dims u32 required Vector dimensionality; immutable once registered.
--normalize flag false L2-normalize vectors at write (enables dot-product search).
--provider-ref string "" Audit label, e.g. openai, local-vllm.
Register an OpenAI embedding model
telha vector register-model --name text-embedding-3-small --dims 1536 \
  --normalize --provider-ref openai --data-dir ./data

telha vector models

Synopsis: telha vector models [RunArgs]

Lists registered embedding models with their dims, normalize flag, provider ref, and model id.

telha vector models --data-dir ./data

telha vector rebuild

Synopsis: telha vector rebuild --tenant <uuid> --org <uuid> --model <name> [--bucket <id>] [RunArgs]

Rebuilds HNSW partitions from the vectors column family for one tenant and model (derived indexes are always rebuildable by design).

Flag Type Default Notes
--tenant UUID required Tenant scope.
--org UUID required Organization scope.
--model string required Model name.
--bucket u64 none (all buckets) Restrict to one time-bucket id.
Rebuild after a restore
telha vector rebuild --tenant $TENANT --org $ORG --model text-embedding-3-small --data-dir ./data

Index administration (index)

telha index rebuild-bitmaps

Synopsis: telha index rebuild-bitmaps --tenant <uuid> --org <uuid> [RunArgs]

Rebuilds one tenant's bitmap predicate index from the version column families. Run this before flipping bitmap.enabled on for existing data. Opens the data dir directly.

telha index rebuild-bitmaps --tenant $TENANT --org $ORG --data-dir ./data
# rebuilt: N rows deleted, M versions scanned, K rows written

Jobs (jobs)

All jobs subcommands open the data dir directly.

telha jobs ls

Synopsis: telha jobs ls --state <state> --tenant <uuid> --org <uuid> [RunArgs]

Lists jobs in one state. --state is one of pending|leased|completed|failed|dead.

telha jobs ls --state dead --tenant $TENANT --org $ORG --data-dir ./data

telha jobs show

Synopsis: telha jobs show <id> --tenant <uuid> --org <uuid> [RunArgs]

Shows one job's full record, including its event log.

telha jobs show <job-uuid> --tenant $TENANT --org $ORG --data-dir ./data

telha jobs retry

Synopsis: telha jobs retry <id> --tenant <uuid> --org <uuid> [RunArgs]

Resets a dead job to pending with a fresh retry budget.

telha jobs retry <job-uuid> --tenant $TENANT --org $ORG --data-dir ./data

Connectors (connector)

Seeds and inspects sync:{source} job chains; the chain itself is the connector state, there is no separate registry. Opens the data dir directly.

telha connector run

Synopsis: telha connector run <source> --tenant <uuid> --org <uuid> [--payload <json>] [RunArgs]

Seeds (or re-seeds) a connector's sync chain with a first job of kind sync:{source}. Refuses a second seed while a pending or leased step already exists for that source.

Flag Type Default Notes
--tenant UUID required Tenant scope.
--org UUID required Organization scope.
--payload JSON string {"v":1} Initial payload (a fresh cursor). 
telha connector run entra --tenant $TENANT --org $ORG --data-dir ./data

telha connector ls

Synopsis: telha connector ls --tenant <uuid> --org <uuid> [RunArgs]

Lists sync jobs across all states for the tenant.

telha connector status

Synopsis: telha connector status <source> --tenant <uuid> --org <uuid> [RunArgs]

Shows the latest chain step for one source: state, cursor age (payload), and its event trail.

telha connector status sharepoint --tenant $TENANT --org $ORG --data-dir ./data

Clarifications (clarify)

The CLI is the local-operator trust boundary: --responder is a declaration recorded with channel "cli" (the REST responder-assertion rule guards the remote surface instead). All subcommands open the data dir directly.

telha clarify ls

Synopsis: telha clarify ls --tenant <uuid> --org <uuid> [--state <state>] [RunArgs]

Lists clarifications, optionally filtered by state: open|attested|partially_confirmed|answered|conflicted|expired|dead_lettered.

telha clarify show

Synopsis: telha clarify show <id> --tenant <uuid> --org <uuid> [RunArgs]

Shows one clarification: candidates, responses, quorum, events, and the delivery job trail (attempt N maps to ranked candidate N; the final attempt is steward escalation).

telha clarify answer

Synopsis: telha clarify answer <id> --tenant <uuid> --org <uuid> --responder <uuid> [--rights <viewer\|editor>] [--index <n>] [--valid-from <ts>] [--valid-to <ts>] [--text <s>] [RunArgs]

Records an answer as a declared person.

Flag Type Default Notes
--responder UUID required The PERSON the answer binds as.
--rights string editor viewer|editor. Passing steward is rejected: use clarify review instead.
--index usize none Candidate index to confirm.
--valid-from string none Free-form valid-time start (µs int or RFC3339); used with a free-form (non-candidate) answer.
--valid-to string none Free-form valid-time end, exclusive.
--text string none Free-form source text kept as evidence.
Confirm ranked candidate 0
telha clarify answer <id> --tenant $TENANT --org $ORG --responder $PERSON --index 0 --data-dir ./data

telha clarify queue

Synopsis: telha clarify queue --tenant <uuid> --org <uuid> [RunArgs]

The steward review queue: clarifications needing attention (open or partially confirmed at high/critical severity, conflicted, expired, dead-lettered), most urgent first.

telha clarify erase-attribution

Synopsis: telha clarify erase-attribution --person <uuid> --tenant <uuid> --org <uuid> [RunArgs]

GDPR: tombstones a person's attribution (asked entries, responder ids, message refs, channel metadata) across every clarification in scope. Confirmation evidence and corrected facts survive.

telha clarify review

Synopsis: telha clarify review <id> --tenant <uuid> --org <uuid> --responder <uuid> [--index <n>] [--valid-from <ts>] [--valid-to <ts>] [--text <s>] [RunArgs]

Steward review: binds an explicit override on a conflicted clarification. --responder is the steward PERSON the override binds as.

Backups (backup)

create opens the data dir exclusively (stop the server, or rely on the in-process [backup] ticker for online backups); verify and restore never touch a live data dir.

telha backup create

Synopsis: telha backup create --out <dir> [--keep <n>] [--pg-database-url <url>] [RunArgs]

Creates and verifies a backup stamp under --out.

Flag Type Default Notes
--out path required Backup target directory; stamp dirs are created inside it.
--keep usize 0 Stamps to retain; 0 = never prune.
--pg-database-url string none App-layer PostgreSQL URL for the two-surface capture. Falls back to the env var named by backup.pg_database_url_env; absent means a core-only backup, marked partial. 
telha backup create --out /var/backups/telha --data-dir /var/lib/telha

telha backup verify

Synopsis: telha backup verify --from <stamp-dir>

Verifies a backup stamp: every file hashes clean, nothing extra. Never touches a live data dir.

telha backup restore

Synopsis: telha backup restore --from <stamp-dir> --data-dir <empty-dir> [--erasure-ledger <path>]

Restores a verified stamp into an empty data dir.

Flag Type Default Notes
--from path required The stamp directory (…/telha-backup-<µs>).
--data-dir path required Empty target data dir.
--erasure-ledger path none Erasure-ledger path to check; a present ledger refuses the restore until ledger replay lands.

Nothing expires without an explicit policy: keep_forever is the default for every selector. Everything opens the data dir directly except the /admin/retention/* REST mirror on a live server.

telha retention policy set

Synopsis: telha retention policy set --tenant <uuid> --org <uuid> (--label <l> | --source-kind <k>) --action <action> [--archive-days <n>] [--delete-days <n>] [--actor <name>] [RunArgs]

Sets (or replaces) the policy for one selector.

Flag Type Default Notes
--label string none Node-label selector (conflicts with --source-kind).
--source-kind string none Source-kind selector (ingest format or connector namespace).
--action string required keep_forever|archive_after|delete_after|archive_then_delete.
--archive-days u32 none Days of tx-time age before archival.
--delete-days u32 none Days of tx-time age before deletion.
--actor string cli Operator recorded on the policy row. 
telha retention policy set --tenant $TENANT --org $ORG \
  --label CONTRACT_DOCUMENT --action archive_then_delete \
  --archive-days 365 --delete-days 730 --data-dir ./data

telha retention policy ls

Synopsis: telha retention policy ls --tenant <uuid> --org <uuid> [RunArgs]

Lists current policies.

telha retention policy rm

Synopsis: telha retention policy rm --tenant <uuid> --org <uuid> (--label <l> | --source-kind <k>) [RunArgs]

Removes one selector's policy (reverting it to keep_forever).

telha retention hold set

Synopsis: telha retention hold set --tenant <uuid> --org <uuid> [--label <l> | --source-kind <k> | --id <uuid>] --reason <text> [--actor <name>] [RunArgs]

Sets a legal hold; omitting --label/--source-kind/--id holds the whole tenant. --reason is mandatory (a compliance artifact).

telha retention hold lift

Synopsis: telha retention hold lift <hold-uuid> --tenant <uuid> --org <uuid> [RunArgs]

Lifts a hold; the record survives with lifted_at set. Prints a warning that matching entities become actionable on the next run.

telha retention hold ls

Synopsis: telha retention hold ls --tenant <uuid> --org <uuid> [RunArgs]

Lists holds, active and lifted (append-only records).

telha retention preview

Synopsis: telha retention preview --tenant <uuid> --org <uuid> [RunArgs]

The normative dry-run: per selector, eligible entities, hold-blocked (with refs), estimated archive size, delete count, and remaining backlog. Never writes.

telha retention run

Synopsis: telha retention run --tenant <uuid> --org <uuid> [RunArgs]

Executes one bounded retention pass for the tenant: archive, then verify (a hard gate), then hold-rechecked deletes, then an orphan sweep. Prints the JSON report and the ledger path.

telha retention archives ls

Synopsis: telha retention archives ls [RunArgs]

Lists archive stamps under the resolved archive directory (retention.archive_dir, or {backup.dir}/archives).

telha retention archives inspect

Synopsis: telha retention archives inspect --from <stamp-dir>

Verifies a stamp and prints its manifest.

telha retention archives sideload

Synopsis: telha retention archives sideload --from <stamp-dir> --data-dir <fresh-empty-dir> [--erasure-ledger <path>]

Side-loads a verified slice into a fresh data dir for inspection; never merges back into the live tenant. Refuses a non-empty target. When --erasure-ledger is given, refuses a slice whose manifest is recorded as superseded by a GDPR erasure.

GDPR erasure (erase)

Operator-scoped, dual-approved, ledgered. The requester counts as approval #1; nothing past preview runs before a second principal approves. There is no blocklist-release subcommand: the blocklist is irrevocable in v1. All subcommands open the data dir directly.

telha erase request

Synopsis: telha erase request --tenant <uuid> --org <uuid> --kind <tenant\|subject> [--person <uuid>]... [--identifier <s>]... [--weak-identifier <s>]... [--whole-source <uuid>]... --legal-ref <ref> --requested-by <name> [--deletion-fallback] [RunArgs]

Creates an erasure request.

Flag Type Default Notes
--kind string required tenant or subject.
--person UUID, repeatable none Subject PERSON logical id.
--identifier string, repeatable none STRONG identifier (email, phone, employee/customer id): the zero-residual gate.
--weak-identifier string, repeatable none WEAK identifier (names/name fragments): reviewable residuals.
--whole-source UUID, repeatable none Source id whose entire content is the subject's (deletion path).
--legal-ref string required Legal basis reference.
--requested-by string required Requesting principal.
--deletion-fallback flag false Whole-blob deletion instead of masking. 
telha erase request --tenant $TENANT --org $ORG --kind subject \
  --person $PERSON --identifier jane@example.com \
  --legal-ref "Art.17-2026-004" --requested-by dpo@example.com --data-dir ./data

telha erase approve

Synopsis: telha erase approve --tenant <uuid> --org <uuid> <id> --principal <name> [RunArgs]

Records the second approval. --principal must differ from the requester.

telha erase preview

Synopsis: telha erase preview --tenant <uuid> --org <uuid> <id> [RunArgs]

Stage-0 preview: per-identifier match counts per surface (blast radius). Never writes.

telha erase execute

Synopsis: telha erase execute --tenant <uuid> --org <uuid> <id> [--operator <name>] [RunArgs]

Executes every remaining stage; resumable at stage boundaries. --operator defaults to cli-operator and is recorded on the completion report attestation.

telha erase verify

Synopsis: telha erase verify --tenant <uuid> --org <uuid> <id> [--operator <name>] [RunArgs]

Runs (or resumes) the verification scan and closes the request.

telha erase status

Synopsis: telha erase status --tenant <uuid> --org <uuid> [id] [RunArgs]

Shows request status (stages, state, approvals). Omit id to list every request in scope.

telha erase report

Synopsis: telha erase report --tenant <uuid> --org <uuid> <id> [RunArgs]

Prints the completion report, the artifact of record for the DPO.

telha erase review

Synopsis: telha erase review --tenant <uuid> --org <uuid> <id> --matched-identifier <s> --store <cf> --object-ref <ref> --decision <d> --reason-code <code> --reason-text <text> --approver-a <name> --approver-b <name> [RunArgs]

Records a dual-approved residual review for a WEAK-identifier scan hit. --decision is one of erased|retained_redacted|waived_non_subject|retained_article_17_3. --approver-a and --approver-b must differ.

Debug (debug)

Operator forensics tools.

telha debug decode-key

Synopsis: telha debug decode-key <cf> <hex>

Decodes a raw storage key (hex, with or without a 0x prefix) under a named column family's layout. No config or data dir needed.

telha debug decode-key node_versions 0x0102...

telha debug index-check

Synopsis: telha debug index-check --tenant <uuid> --org <uuid> [RunArgs]

Cross-verifies one tenant's covering temporal indexes against the primary column families; a healthy tenant reports zero findings. Opens the data dir directly.

telha debug index-check --tenant $TENANT --org $ORG --data-dir ./data
# index-check: clean (0 missing, 0 orphaned)