CLI Reference

The SynDB CLI (syndb) provides command-line access to account management, saved queries, dataset upload, federation, ETL, and Kubernetes workflows.

This page documents the current command surface. If you are working from this repository, you can run the CLI directly without a global install:

cargo run -p cli --features full -- --help

If the repository was cloned without submodules, initialize them first:

git submodule update --init --recursive

Global Options

Commands

user — account management

• syndb auth register — create a new account
• syndb auth login — authenticate and store the token locally
• syndb auth logout — revoke the current session

query — saved queries and SyQL helpers

These saved-query commands operate on the server-backed QueryFabric path, not a local on-disk query store.

syndb query list
syndb query save --label "Neuron subset" --table 1 --dataset-id <uuid> --column neuron_id --column cell_type
syndb query save-syql --label "Mouse neurons" "FROM neurons WHERE species = 'mouse' LIMIT 1000"
syndb query show <query-id>
syndb query update <query-id> --label "Updated label"
syndb query run <query-id>
syndb query status <query-id>
syndb query delete <query-id>
syndb query exec "FROM neurons LIMIT 10"
syndb query explain "FROM neurons LIMIT 10"

Current subcommands: save, list, show, update, delete, run, status, save-syql, exec, and explain.

dataset — dataset management

syndb data new --label "Example dataset" --animal "Mus musculus" --microscopy EM --table 1 --brain-structure hippocampus
syndb data prepare --input-dir raw_dataset --output-dir prepared_dataset
syndb data validate --input-dir prepared_dataset
syndb data upload --input-dir prepared_dataset --dataset-id <uuid>
syndb data download --dataset-id <uuid> --output-dir download_dir
syndb data mesh-upload --dataset-id <uuid> --input-dir meshes
syndb data swb-upload --dataset-id <uuid> --input-dir swb
syndb data delete --dataset-id <uuid>
syndb data search reconcile --dry-run
syndb data cache-tags
syndb data gen-test-data --output-dir tmp/test-data

Current subcommands: new, prepare, validate, upload, download, mesh-upload, swb-upload, delete, search reconcile, cache-tags, and gen-test-data.

syndb data search reconcile is the repair path for public full-text search. It rebuilds the local portion of the shared datasets Meilisearch index from PostgreSQL, preserves federated documents, and deletes stale local entries. Use --dry-run to inspect the planned changes without mutating Meilisearch.

The reconcile command reads its runtime contract from environment variables:

• POSTGRES_HOST / POSTGRES_READ_HOST
• POSTGRES_PORT
• POSTGRES_USERNAME
• POSTGRES_PASSWORD
• POSTGRES_PATH
• MEILISEARCH_URL
• MEILISEARCH_API_KEY

Example:

POSTGRES_HOST=localhost \
POSTGRES_READ_HOST=localhost \
POSTGRES_PORT=5433 \
POSTGRES_USERNAME=syndb \
POSTGRES_PASSWORD=syndb \
POSTGRES_PATH=syndb_test \
MEILISEARCH_URL=http://localhost:7700 \
MEILISEARCH_API_KEY=meili_dev_key \
syndb data search reconcile --dry-run

etl — dataset import pipeline

Most datasets support download, validate, and import subcommands. CAVE-backed datasets may use manual export instead of download, followed by validate and import:

syndb etl <dataset> download       # when a static release exists
syndb etl <dataset> validate
syndb etl <dataset> import --data-dir external_datasets/<name> --table neurons --dataset-id <uuid>

spine-morphometry is the main special case: it uses --source kasthuri|ofer-confocal|microns instead of separate dataset keys.

Dataset keys

Additional ETL utility commands: seed, update-all, and status.

federation — federation management

syndb ops federation init --cluster-name my-lab-node --clickhouse-endpoint clickhouse.mylab.edu --federation-password "$SYNDB_FEDERATION_PASSWORD"
syndb ops federation status
syndb ops federation sync-schema --dry-run
syndb ops federation test
syndb ops federation clusters
syndb ops federation logout

See Node Setup for detailed usage.

graph-precompute — Batch Graph Computation

syndb graph-precompute --dataset flywire

Pre-computes graph metrics and stores results in ClickHouse materialized tables for one or more current dataset keys.

k8s — Kubernetes administration

Current top-level groups:

• syndb ops k8s etl — ETL jobs on Kubernetes
• syndb ops k8s secrets — secret management helpers
• syndb ops k8s sites — federation site helpers

Common ETL operations:

syndb ops k8s etl status
syndb ops k8s etl report
syndb ops k8s etl watch
syndb ops k8s etl retry
syndb ops k8s etl cleanup
syndb ops k8s etl reset

bench — Benchmarking

Performance testing suite for API and federation queries.

syndb-plot — Manuscript figures

The plotting package exposes a separate syndb-plot CLI for benchmark plots and manuscript figure rendering.

Benchmark-backed manuscript panels read benchmark/results/ by default. To render against a production benchmark bundle elsewhere, pass the directory explicitly:

syndb-plot manuscript-panels \
  --benchmark-results-dir documentation/manuscript/benchmarks/cluster-rebuild-2026-05-23

The same flag is available on focused panel/build commands:

syndb-plot manuscript-inspect-panel 5 A --benchmark-results-dir <results-dir>
syndb-plot manuscript-build-one 5 --benchmark-results-dir <results-dir>

manuscript-panels uses the provided directory for its benchmark preflight and for benchmark-backed composite figures. manuscript-composites only compiles already-rendered panels and does not read benchmark parquet.

ci — CI helpers

Internal build, test, and image automation helpers used by project workflows.

completions — Shell Completions

syndb completions bash > ~/.local/share/bash-completion/completions/syndb
syndb completions zsh > ~/.zfunc/_syndb
syndb completions fish > ~/.config/fish/completions/syndb.fish