Dremio Developer CLI

The Dremio Developer CLI (dremio) gives you full programmatic access to Dremio from the terminal or any automation pipeline. It wraps the Dremio REST API into a consistent set of commands covering queries, catalog management, Reflections, engines, users, roles, grants, and projects, without needing to hand-craft API calls.

Whether you're querying data from a pipeline, debugging a job from the terminal, or building an agent that interacts with Dremio, the CLI provides a consistent interface with structured output and predictable error handling.

Install

You can install the Dremio Developer CLI using pipx, uv, or pip. Python 3.11 or later is required.

The package name is dremio-cli. Do not install dremio-client, which is an unrelated third-party package.

pipx (Recommended)
uv
pip

Install with pipx

pipx install dremio-cli

Verify the installation

dremio --help

Install with uv

uv tool install dremio-cli

Verify the installation

dremio --help

Install with pip

pip install dremio-cli

Verify the installation

dremio --help

note

On modern macOS and Linux, pip install into the system Python may fail with an externally-managed-environment error. Use pipx or uv tool install instead. Both create an isolated environment automatically.

Authenticate

The CLI requires a personal access token (PAT) and your Dremio project ID. CLI flags take priority over environment variables, which take priority over the config file.

Your API endpoint depends on your control plane region:

Control Plane	URI
US	`https://api.dremio.cloud`
EU	`https://api.eu.dremio.cloud`

Interactive setup (Recommended)
Config file
Environment variables
CLI flags

Run the interactive setup to configure credentials:

Run interactive setup

dremio setup

The setup command walks you through region selection, PAT creation, and project ID discovery, then validates your credentials and writes the config file to ~/.config/dremioai/config.yaml.

tip

This config file is shared with the Dremio MCP Server, so no duplicate configuration is needed if you use both.

Create ~/.config/dremioai/config.yaml:

~/.config/dremioai/config.yaml

pat: your-personal-access-token
project_id: your-project-id
uri: https://api.dremio.cloud

tip

This config file is shared with the Dremio MCP Server, so no duplicate configuration is needed if you use both.

Environment variables

export DREMIO_TOKEN=your-personal-access-token
export DREMIO_PROJECT_ID=your-project-id
export DREMIO_URI=https://api.dremio.cloud

Pass credentials directly on any command:

Example using CLI flags

dremio --token your-pat --project-id your-project-id --uri https://api.dremio.cloud query run "SELECT 1"

Run a Query

You can run a SQL query directly from the terminal using dremio query run.

Run a SQL query

dremio query run "SELECT 1 AS hello"

You can also run SQL from a file or pipe it via stdin:

Run SQL from a file

dremio query run --file query.sql

Run SQL from stdin

cat query.sql | dremio query run -

Chat with the AI Agent

You can use dremio chat to have a conversation with Dremio's AI agent directly from the terminal.

Interactive Mode

Running dremio chat launches an interactive session with a You > prompt. The agent has access to your catalog, schemas, jobs, and Reflections, and can run queries on your behalf.

Start an interactive chat session

dremio chat

Use --conversation to resume a previous session, --log-file to write a JSON-lines event log, and --model to override the model.

Resume a previous conversation

dremio chat --conversation <conversation-id>

The following slash commands are available within the session:

Command	Description
`/new`	Start a new conversation
`/list`	List recent conversations
`/continue <id>`	Resume a previous conversation
`/history`	Show message history for the current conversation
`/cancel`	Cancel the current running request
`/delete <id>`	Delete a conversation
`/info`	Show the current conversation and run ID
`/help`	Show available commands
`/quit`	Exit the session

To manage conversations from the terminal before starting a session, use dremio chat list, dremio chat history <id>, and dremio chat delete <id> instead.

Non-Interactive Mode

Use --message to send a single message and stream the response to stdout. This is useful for scripting and pipelines. Use --auto-approve to automatically approve any tool calls the agent makes.

Send a single message

dremio chat --message "Which tables in the Analytics space have failed Reflections?"

Send a single message and auto-approve tool calls

dremio chat --message "Refresh all stale Reflections in the Analytics space" --auto-approve

Format Output

All commands output JSON by default. Use --output to change the format:

Format	Flag	Best for
JSON	`--output json`	Pipelines, agents, scripting
CSV	`--output csv`	Data export, spreadsheets
Pretty	`--output pretty`	Terminal review

Filter Output

Use --fields with dot notation to return only the fields you need:

Filter output fields

dremio schema describe myspace.orders --fields fields.name,fields.type
dremio job list --fields job_id,job_state,start_time

Validate Before You Execute

Append --dry-run to validate a destructive command before executing it:

Dry run before refreshing a Reflection

dremio reflection refresh <reflection-id> --dry-run
dremio reflection refresh <reflection-id>

Example: Autonomous Data Investigation

Here's what an agent session looks like in practice when investigating why a report is showing unexpected numbers, from first command to resolution:

Autonomous investigation workflow

# Search the catalog for relevant datasets
dremio search "revenue" --output json

# Inspect the table schema
dremio schema describe Analytics.production.quarterly_revenue --output json

# Trace where the data comes from
dremio schema lineage Analytics.production.quarterly_revenue

# Query the data directly
dremio query run "SELECT quarter, region, SUM(revenue)
  FROM Analytics.production.quarterly_revenue
  WHERE fiscal_year = 2026
  GROUP BY quarter, region" --output json

# Check for failed refresh jobs
dremio job list --status FAILED --output json \
  --fields job_id,dataset,start_time,error_message

# List Reflections on the table
dremio reflection list Analytics.production.quarterly_revenue --output json

# Validate and then apply the refresh
dremio reflection refresh <reflection-id> --dry-run
dremio reflection refresh <reflection-id>

Build Agents with Python

If you're building a Python application or agent, you can import the CLI functions directly instead of running commands from the terminal:

Python library import

from drs.auth import load_config
from drs.client import DremioClient
from drs.commands.query import run_query

config = load_config()
client = DremioClient(config)
result = await run_query(client, "SELECT * FROM myspace.orders LIMIT 10")
await client.close()

Command Introspection

Use dremio describe to get the full parameter schema for any command:

Introspect a command

dremio describe query.run

Output

{
  "group": "query",
  "command": "run",
  "description": "Execute a SQL query against Dremio Cloud, wait for completion, return results.",
  "mechanism": "REST",
  "endpoints": [
    "POST /v0/projects/{pid}/sql",
    "GET /v0/projects/{pid}/job/{id}",
    "GET /v0/projects/{pid}/job/{id}/results"
  ],
  "parameters": [
    { "name": "sql", "type": "string", "required": true, "positional": true, "description": "SQL query to execute" },
    { "name": "output", "type": "enum", "required": false, "default": "json", "enum": ["json", "csv", "pretty"] },
    { "name": "fields", "type": "string", "required": false, "flag": "--fields/-f", "description": "Comma-separated fields to include" }
  ]
}

Command Reference

The following tables list all available commands, grouped by function.

Setup

Command	Description
`dremio setup`	Interactive setup to configure credentials (region, PAT, project ID)

Chat

Command	Description
`dremio chat`	Start an interactive chat session with the AI agent
`dremio chat --message "<prompt>"`	Send a single message (non-interactive)
`dremio chat list`	List recent conversations
`dremio chat history <id>`	Show message history for a conversation
`dremio chat delete <id>`	Delete a conversation

Query

Command	Description
`dremio query run "<sql>"`	Submit SQL, poll to completion, return all rows
`dremio query run --file <path>`	Submit SQL from a file
`dremio query status <job-id>`	Get current status of a running job
`dremio query cancel <job-id>`	Cancel a running job

Schema and Catalog

Command	Description
`dremio schema describe <path>`	Column names and types for a table or view
`dremio schema lineage <path>`	Upstream and downstream dependency graph
`dremio schema sample <path>`	Preview rows from a table
`dremio search <term>`	Full-text search across all catalog entities
`dremio folder list <path>`	List contents of a space or folder
`dremio folder get <path>`	Get metadata for a space or folder
`dremio folder create <path>`	Create a space or folder
`dremio folder delete <path>`	Delete a space or folder
`dremio folder grants <path>`	View grants on a space or folder

Metadata

Command	Description
`dremio wiki get <path>`	Read wiki documentation for a catalog entity
`dremio wiki update <path>`	Write wiki documentation for a catalog entity
`dremio tag get <path>`	Read tags on a catalog entity
`dremio tag update <path>`	Write tags on a catalog entity

Jobs

Command	Description
`dremio job list`	List recent jobs (supports `--status FAILED` filter)
`dremio job get <job-id>`	Get details for a specific job
`dremio job profile <job-id>`	Operator-level execution profile for performance analysis

Reflections

Command	Description
`dremio reflection list`	List all Reflections in the project
`dremio reflection get <id>`	Get details for a specific Reflection
`dremio reflection create`	Create a new Reflection
`dremio reflection refresh <id>`	Force-refresh a Reflection
`dremio reflection delete <id>`	Delete a Reflection

Engines

Command	Description
`dremio engine list`	List all engines
`dremio engine get <id>`	Get engine details
`dremio engine create`	Create a new engine
`dremio engine update <id>`	Update engine configuration
`dremio engine enable <id>`	Enable an engine
`dremio engine disable <id>`	Disable an engine
`dremio engine delete <id>`	Delete an engine

Users and Access

Command	Description
`dremio user list`	List all users in the organization
`dremio user get <id>`	Get user details
`dremio user create`	Invite a new user
`dremio user delete <id>`	Remove a user
`dremio user whoami`	Show the currently authenticated user
`dremio user audit <username>`	Trace all role memberships and effective grants for a user
`dremio role list`	List all roles
`dremio role get <id>`	Get role details
`dremio role create`	Create a new role
`dremio role update <id>`	Update a role
`dremio role delete <id>`	Delete a role
`dremio grant get`	View grants on a resource
`dremio grant update`	Update grants on a resource
`dremio grant delete`	Remove grants from a resource

Projects

Command	Description
`dremio project list`	List all projects in the organization
`dremio project get <id>`	Get project details
`dremio project create`	Create a new project
`dremio project update <id>`	Update a project
`dremio project delete <id>`	Delete a project

Introspection

Command	Description
`dremio describe <command>`	Return machine-readable JSON schema for any command

Global Flags

These flags apply to all commands:

Flag	Description
`--token`	PAT for authentication
`--project-id`	Dremio project ID
`--uri`	Dremio API endpoint (default: `https://api.dremio.cloud`)
`--config`	Path to config file
`--output` / `-o`	Output format: `json` (default), `csv`, `pretty`
`--fields` / `-f`	Comma-separated dot-notation field filter

Connect AI Agents to Dremio with MCP – Connect Claude and ChatGPT to Dremio.
API Reference – Full REST API documentation.
GitHub - dremio/cli/issues

Install​

Authenticate​

Run a Query​

Chat with the AI Agent​

Interactive Mode​

Non-Interactive Mode​

Format Output​

Filter Output​

Validate Before You Execute​

Example: Autonomous Data Investigation​

Build Agents with Python​

Command Introspection​

Command Reference​

Setup​

Chat​

Query​

Schema and Catalog​

Metadata​

Jobs​

Reflections​

Engines​

Users and Access​

Projects​

Introspection​

Global Flags​

Related Topics​

Install

Authenticate

Run a Query

Chat with the AI Agent

Interactive Mode

Non-Interactive Mode

Format Output

Filter Output

Validate Before You Execute

Example: Autonomous Data Investigation

Build Agents with Python

Command Introspection

Command Reference

Setup

Chat

Query

Schema and Catalog

Metadata

Jobs

Reflections

Engines

Users and Access

Projects

Introspection

Global Flags

Related Topics