Datris CLI - Datris

The Datris CLI (datris) is a command-line interface for the Datris Data Platform. It communicates with the platform via the MCP server, providing a simple way to ingest data, run queries, search vector stores, and manage pipelines — all from the terminal.

Installation

brew tap datris/tap
brew install datris

Configuration

The CLI connects to the MCP server via SSE. Set the server URL with an environment variable:

export MCP_SERVER_URL=http://localhost:3000/sse    # default

Authentication

When USE_API_KEYS=false (the OSS default) no key is needed. When USE_API_KEYS=true, export the key and the CLI sends it as the x-api-key header on every request to the MCP server:

export DATRIS_API_KEY=<your key>

If the key is missing or wrong, commands stop with a one-line message telling you to set DATRIS_API_KEY.

Older CLI versions do not read DATRIS_API_KEY. For those, put the key on the MCP URL’s query string instead, which the MCP server still accepts: export MCP_SERVER_URL="http://localhost:3000/sse?api_key=<your key>".

Issue a key dedicated to the CLI from the UI: Configuration → API-Keys → Issue new key. See API Keys for the full pattern.

JSON Output

Every command except tap delete supports --json to return raw JSON instead of human-readable output. This is useful for scripting and programmatic use.

datris pipelines --json
datris query "SELECT * FROM trades" --json
datris analyze "top 5 stocks" --table trades --json
datris health --json

Commands

`datris help`

Show all available commands and options.

datris --help

`datris pipelines`

List all registered pipelines.

datris pipelines

`datris ingest`

Create a pipeline and ingest a data file in one step. The schema is auto-detected from the file. If the named pipeline already exists, the existing config is preserved and the file is uploaded into it — --dest, --table, --ai-validate, --ai-transform, and --catalog are ignored on re-ingest. Delete the pipeline first (datris delete <name>) if you need a fresh config.

datris ingest <FILE> [OPTIONS]

Option	Description
`--pipeline, -p`	Pipeline name (default: derived from filename)
`--dest, -d`	Destination: `postgres`, `mongodb`, `snowflake`, `databricks`, `qdrant`, `weaviate`, `milvus`, `chroma`, `pgvector` (default: `postgres`)
`--table, -t`	Table/collection name (default: pipeline name)
`--database`	Database name (default: `datris`). For `snowflake`: the Snowflake database; for `databricks`: the Unity Catalog name — required for both
`--schema`	Destination schema (`snowflake` default: `PUBLIC`; `databricks` default: `default`)
`--warehouse`	Snowflake warehouse name, or Databricks SQL warehouse ID (required for Snowflake; for Databricks, optional when the secret has a `warehouse` field)
`--credentials-secret`	Platform secret holding destination credentials (required for `snowflake` and `databricks`)
`--ai-validate`	AI data quality rule — plain-English instruction
`--ai-transform`	AI transformation instruction — plain-English instruction
`--ai-analyze`	Ask a question about the data after ingestion completes
`--catalog`	Catalog label to group this pipeline with related pipelines (e.g. `openclaw`). Free-form — no need to pre-create. Only applied when creating a new pipeline.
`--json`	Return raw JSON

Examples:

# Basic ingestion — auto-derives pipeline name from filename
datris ingest sales-data.csv --dest postgres

# With explicit pipeline name
datris ingest sales-data.csv --pipeline sales --dest postgres

# With AI validation
datris ingest trades.csv --dest postgres --ai-validate "all prices must be positive and dates must be YYYY-MM-DD"

# With AI transformation
datris ingest trades.csv --dest postgres --ai-transform "convert all date columns to YYYY/MM/DD format"

# Both validation and transformation
datris ingest trades.csv --dest postgres \
  --ai-validate "all prices must be positive" \
  --ai-transform "convert dates to YYYY/MM/DD and uppercase all ticker symbols"

# Ingest into MongoDB
datris ingest events.json --dest mongodb --database analytics

# Ingest into Snowflake (credentials come from a Platform secret)
datris ingest trades.csv --dest snowflake --database ANALYTICS \
  --warehouse COMPUTE_WH --credentials-secret snowflake-creds

# Ingest into a vector store for RAG
datris ingest manual.pdf --dest pgvector

# Group related pipelines under a catalog
datris ingest legal-2026.pdf --pipeline legal_2026 --dest pgvector --catalog legal

# Ingest + analyze in one command
datris ingest trades.csv --dest postgres --ai-analyze "What are the top 5 stocks by volume?"

# Ingest a document and ask a question about it
datris ingest annual-report.pdf --dest pgvector --ai-analyze "What was the company's revenue?"

# Ingest + analyze, raw JSON output for scripts
datris ingest trades.csv --dest postgres --ai-analyze "top 5 by volume" --json

`datris query`

Execute a read-only SQL SELECT query against PostgreSQL.

datris query "SELECT * FROM public.sales LIMIT 10"
datris query "SELECT symbol, close FROM public.trades WHERE close > 100" --limit 50

Option	Description
`--limit`	Max rows returned (default: 100; pass `-1` for no limit)
`--json`	Return raw JSON

`datris search`

Semantic search across a vector database.

datris search "What is the return policy?" --store pgvector --collection support_docs

Option	Description
`--store`, `-s`	Vector store: `qdrant`, `weaviate`, `milvus`, `chroma`, `pgvector` (default: `pgvector`)
`--collection`, `-c`	Collection/table name (required)
`--top-k`, `-k`	Number of results (default: 5)
`--json`	Return raw JSON

`datris analyze`

Ask a question about your data using AI. Works with any destination type — auto-picks the right approach based on --dest.

datris analyze <QUESTION> --table <TABLE> [OPTIONS]

Option	Description
`--table, -t`	Table/collection name (required)
`--dest, -d`	Data source type: `postgres`, `mongodb`, `snowflake`, `databricks`, `sqlserver`, `qdrant`, `weaviate`, `milvus`, `chroma`, `pgvector` (default: `postgres`)
`--pipeline, -p`	Pipeline name (required for `snowflake`/`databricks`/`sqlserver` — the pipeline selects the connection)
`--top-k, -k`	Number of search results for vector stores (default: 5)
`--json`	Return raw JSON instead of AI narrative

Examples:

# Analyze PostgreSQL data — AI generates SQL, executes it, returns AI answer
datris analyze "What are the top 5 stocks by volume?" --table trades

# Analyze MongoDB data
datris analyze "How many events occurred in March?" --table events --dest mongodb

# Analyze a Snowflake, Databricks or SQL Server destination — pipeline selects the connection
datris analyze "Which region had the most sales?" --table sales --dest snowflake --pipeline sales

# Analyze vector store data (RAG) — semantic search + AI answer
datris analyze "What is the return policy?" --table support_docs --dest pgvector
datris analyze "What was quarterly revenue?" --table financial_docs --dest qdrant

# Raw JSON output for scripts
datris analyze "top 5 stocks" --table trades --json

How it works by destination:

PostgreSQL — AI generates a SQL query from your question, executes it, then summarizes the results in a natural language answer
MongoDB — fetches documents from the collection, then AI answers the question based on the data
Snowflake / Databricks / SQL Server — previews up to 100 rows from the pipeline’s destination table (connection and credentials resolved server-side from the pipeline config), then AI answers the question based on the data
Vector stores — performs semantic search to find relevant chunks, then AI generates an answer from the retrieved context

`datris query-mongo`

Query a MongoDB collection with optional filter and projection.

datris query-mongo events
datris query-mongo events --filter '{"status": "active"}' --limit 20
datris query-mongo events --projection '{"name": 1, "status": 1}'

Option	Description
`--filter`, `-f`	MongoDB filter JSON (default: `{}`)
`--projection`	Fields to include/exclude
`--limit`	Max documents (default: 20)
`--json`	Return raw JSON

`datris status`

Get the latest job status for a pipeline.

datris status my_pipeline

`datris pipeline result`

Read the rows a Live Read pipeline (the scratch destination) produced. TOKEN is the pipeline token returned when the pipeline ran. Only Live Read pipelines have a result; results expire after the retention window, after which the command says to run the pipeline again.

datris pipeline result <TOKEN> [OPTIONS]

Option	Description
`--offset`	Row offset to start from (default 0)
`--limit`	Rows per page (server default and cap apply; the server clamps it, so page with the `--offset` the output suggests)
`--out FILE`	Write every row as one JSON object per line to this file, paging until the result is exhausted
`--json`	Return raw JSON

datris pipeline result <token>                   # first page, with "showing N of M, expires at ..."
datris pipeline result <token> --offset 100      # next page
datris pipeline result <token> --out rows.jsonl  # everything, as JSON Lines

Exits 1 on an error, including a non-Live-Read pipeline or an expired result.

`datris delete`

Delete a pipeline configuration together with its destination data.

datris delete my_pipeline

Option	Description
`--json`	Return raw JSON

Deleting a pipeline always deletes its destination data. --keep-data is not supported: it exits with an error and deletes nothing. To keep the data, copy it or point a new pipeline at the same prefix before deleting. Any warnings the server returns (for example, a Unity Catalog table an admin still has to drop) are printed after the success line, one per line, prefixed with ⚠.

`datris health`

Check the health of all backend services.

datris health

`datris secrets`

List all configured secrets.

datris secrets

`datris taps`

List all taps.

datris taps

`datris tap create`

Create a tap. The instruction argument (a plain-English description) is optional — provide it to have AI generate the fetch script, or omit it and supply your own script with --script (or create a config-only tap with neither).

datris tap create ["<instruction>"] --pipeline <name> [--name <tap-name>] [--script <file>] [--cron "<expression>"] [--type structured|document] [--kind python|http --endpoint-url <url>]

Argument	Description
`instruction`	Optional plain-English description of the data to fetch. When provided, AI generates the script. Omit when using `--script` or creating a config-only tap

Option	Description
`--pipeline`, `-p`	Target pipeline name
`--name`, `-n`	Tap name (default: derived from pipeline or instruction)
`--cron`	CRON expression for scheduling (Quartz format)
`--secret`	Vault secret name for credentials injected as env vars
`--script`	Path to a Python script file with a `fetch()` function (skips AI generation)
`--type`	`structured` (default) returns rows of records; `document` returns `{uri, filename, content}` dicts destined for a vector-store pipeline. See Document Taps
`--kind`	Tap implementation kind: `python` (default) runs a script on the platform; `http` calls a user-hosted endpoint speaking the tap HTTP contract (no instruction or `--script`)
`--endpoint-url`	For `--kind http`: absolute http(s) URL Datris POSTs the run context to on each run (required with `--kind http`)
`--json`	Return raw JSON

Examples:

# Structured: rows into a Postgres/Mongo pipeline
datris tap create "Fetch daily stock prices for S&P 500 from yfinance" --pipeline stocks --cron "0 0 0 * * ?"
datris tap create "Get weather data from Open-Meteo API" --pipeline weather --name weather-tap

# Document: raw file bytes into a vector-store pipeline
datris tap create "Discover all PDFs in the S3 bucket 'contracts' under prefix 2026/" \
  --pipeline contracts-vec --type document --secret aws-creds

Document taps require a target pipeline whose source is unstructuredAttributes and whose destination is a vector store (qdrant, pgvector, weaviate, milvus, or chroma). The server rejects tap create --type document against a structured pipeline with HTTP 400.

`datris tap run`

Run a tap manually. Output reflects whether the fetched records actually landed in the target pipeline:

$ datris tap run stock-prices
  Running tap 'stock-prices'...
  ✓ success — 33 records fetched
    → persisted to stock-prices
    → watch: datris status stock-prices

Or if the run succeeded but records weren’t persisted (missing target pipeline, test mode, script error, zero records), the CLI tells you exactly why:

  ✓ success — 33 records fetched
    → not persisted (no_target_pipeline)

Pass --json to get the full response including mode, persisted, persistedReason, publisherToken, and pipelineTokens.

`datris tap show`

Show full details of a tap, including its script. Prints the name, description, target pipeline, schedule, enabled state, secret, and last run/test results, followed by the stored script.

datris tap show <name>

Option	Description
`--json`	Return raw JSON

`datris tap test`

Test-run a tap without pushing the fetched records to the target pipeline. Reports the run status, record count, and data type.

datris tap test <name>

Option	Description
`--limit`	Max records to pull for the preview (default: 20; `0` = no cap, streams the whole source)
`--json`	Return raw JSON

`datris tap logs`

Show the run history for a tap — each entry’s timestamp, status, mode (run or test), record count, duration, and any error.

datris tap logs <name>

Option	Description
`--json`	Return raw JSON

`datris tap update`

Update a tap’s configuration without regenerating its script. Specify at least one option.

datris tap update <name> [--enabled | --disabled] [--cron "<expression>"] [--pipeline <name>] [--description "<text>"] [--endpoint-url <url>]

Option	Description
`--enabled` / `--disabled`	Enable or disable the tap
`--cron`	CRON expression for scheduling (Quartz format)
`--pipeline`, `-p`	Target pipeline name
`--description`, `-d`	New description
`--endpoint-url`	New endpoint URL (HTTP taps only)
`--json`	Return raw JSON

`datris tap delete`

Delete a tap.

datris tap delete <name>

`datris catalog export`

Download a catalog as a zip archive: every tap and pipeline in it, each tap’s script and incremental state, and the validation schemas its pipelines reference. Secret values, destination data, run history and version history are never included. The command prints how many taps and pipelines the archive holds and which secrets the catalog needs.

datris catalog export <NAME> [OPTIONS]

Option	Description
`--out`	Archive file to write (default: `<NAME>.zip`)
`--json`	Print the raw tool result (includes the archive as base64)

Example:

datris catalog export sales --out sales-backup.zip

Uncataloged is not a catalog and cannot be exported. On an error nothing is written and the command exits 1.

`datris catalog restore`

Restore an archive made by datris catalog export, under the same name or a new one. A restore never merges into an existing catalog: it is refused when the catalog already exists, when any archived tap or pipeline name already exists anywhere on this install, or (with GitHub script storage) when an AI script file of a new pipeline differs at branch head, and each clash is printed. Restored taps start disabled; test each one and then enable it. Secrets are never written: the command names any secret the restored items need that does not exist yet.

datris catalog restore <FILE> [OPTIONS]

Option	Description
`--as`	Catalog name to restore into (default: the name stored in the archive). Letters, digits, `_` and `-` only
`--overwrite`	Replace the items already in the target catalog instead of creating a new one. Asks you to type the catalog name to confirm
`--yes`	Skip the `--overwrite` confirmation prompt (for scripts)
`--no-state`	Skip each tap’s incremental state, so a clone starts from scratch instead of from the source’s cursor
`--regenerate-scripts`	Regenerate each pipeline’s AI data-quality and transformation scripts on this install instead of restoring the archived ones. Without it, the archived scripts become the live scripts and the command prints `Imported N AI scripts`, plus `Regenerated N AI scripts` or `Kept N AI scripts` (a matching live script left in place) with the reason for any it could not import
`--json`	Print the raw tool result

Examples:

# Restore under a new name
datris catalog restore sales-backup.zip --as sales_restored

# Clone without the source taps' incremental state
datris catalog restore sales-backup.zip --as sales_copy --no-state

# Replace the contents of an existing catalog
datris catalog restore sales-backup.zip --as sales --overwrite

Tap and pipeline names are unique across the install, so restoring onto the same install under a new name is refused while the source catalog still exists: delete or rename the source first. The command exits 1 on an error, on a refusal, and when some items could not be restored (each is printed with its reason).

`datris version`

Get the server version. When the server has an environment label (DATRIS_ENV), it is printed too.

datris version

  Server: {'version': '1.53.0', ..., 'environmentLabel': 'qa', 'mcpServerVersion': '1.53.0'}
  CLI: 1.53.0
  Environment: qa

`datris doctor`

Operational self-check: the server’s own checks (Vault token expiry, AI slot secrets, embedding model loaded, disk, version skew) plus host checks that need Docker (anonymous volumes, container env drift, orphaned containers, stale source build). Every finding prints the command that fixes it; nothing is changed. See Doctor for the full check list.

datris doctor                   # human-readable report
datris doctor --json            # the same report as JSON
datris doctor --probes ai       # also confirm each AI model answers (spends a few tokens)
datris doctor --pre-upgrade     # host checks only — run before every upgrade

Option	Description
`--pre-upgrade`	Host checks plus the AI slot secrets via the vault container; works with the server stopped. Prints the upgrade command when clean.
`--probes ai`	Opt in to the AI reachability probe
`--json`	Print the merged report as JSON
`--project-dir DIR`	Directory holding `docker-compose.yml` and `.env` (default: current directory)
`--compose-file FILE`	Compose file to inspect (e.g. `docker-compose.standalone.yml`)

Unlike the other commands, doctor calls the server’s REST API directly rather than going through the MCP server (DATRIS_URL, default http://localhost:8080). It reads the same DATRIS_API_KEY as every other command when API keys are on — a dead MCP server is itself a finding, not a reason to fail. Exit codes: 0 all ok, 1 any warning, 2 any error, 3 server unreachable (host checks still ran).

Pipeline Name Auto-Detection

When --pipeline is not specified, the CLI derives the pipeline name from the filename:

sales-data.csv → sales_data
Q1 Revenue Report.csv → q1_revenue_report
trades.json → trades

The extension is stripped, hyphens and spaces are replaced with underscores, and the name is lowercased.

​Installation

​Configuration

​Authentication

​JSON Output

​Commands

​datris help

​datris pipelines

​datris ingest

​datris query

​datris search

​datris analyze

​datris query-mongo

​datris status

​datris pipeline result

​datris delete

​datris health

​datris secrets

​datris taps

​datris tap create

​datris tap run

​datris tap show

​datris tap test

​datris tap logs

​datris tap update

​datris tap delete

​datris catalog export

​datris catalog restore

​datris version

​datris doctor

​Pipeline Name Auto-Detection

Installation

Configuration

Authentication

JSON Output

Commands

`datris help`

`datris pipelines`

`datris ingest`

`datris query`

`datris search`

`datris analyze`

`datris query-mongo`

`datris status`

`datris pipeline result`

`datris delete`

`datris health`

`datris secrets`

`datris taps`

`datris tap create`

`datris tap run`

`datris tap show`

`datris tap test`

`datris tap logs`

`datris tap update`

`datris tap delete`

`datris catalog export`

`datris catalog restore`

`datris version`

`datris doctor`

Pipeline Name Auto-Detection