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

The CLI does not set an x-api-key header itself. When USE_API_KEYS=false (the OSS default) no key is needed. When USE_API_KEYS=true, pass the key on the MCP URL’s query string, which the MCP server accepts as an alternative to the header:

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 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 those destinations)
`--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`, `qdrant`, `weaviate`, `milvus`, `chroma`, `pgvector` (default: `postgres`)
`--pipeline, -p`	Pipeline name (required for `snowflake`/`databricks` — 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 or Databricks 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 — previews 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 delete`

Delete a pipeline configuration and optionally its destination data.

datris delete my_pipeline
datris delete my_pipeline --keep-data

Option	Description
`--keep-data`	Keep destination data (only delete the pipeline config)
`--json`	Return raw JSON

`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 pipeline status --publisher 5b2f4a1d-8c7e-4f0a-9b3d-6e1c2a4f8b9e

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
`--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 version`

Get the server version.

datris version

`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 (DATRIS_URL, default http://localhost:8080; DATRIS_API_KEY 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 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 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 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 version`

`datris doctor`

Pipeline Name Auto-Detection