Dremio CLI

The Dremio 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

Requirements: Python 3.11+

Install with pip

pip install dremio-cli

Verify the installation

dremio --help

Install with uv

uv tool install dremio-cli

Verify the installation

dremio --help

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`

Config file (recommended)
Environment variables
CLI flags

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"

Use the CLI

Once authenticated, you're ready to start using the CLI. The sections below cover the core capabilities, from discovering what commands are available to building agents that call the library directly.

Discover Commands

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" }
  ]
}

Run a Query

Run a SQL query

dremio query run "SELECT 1 AS hello"

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 Reference

Query

Command	Description
`dremio query run "<sql>"`	Submit SQL, poll to completion, return all rows
`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.

Support

The Dremio CLI is an open-source project and is not covered by Dremio Support Policies. For issues and feature requests, see:

GitHub Issues: dremio/cli/issues
Community: Dremio Community
Contributing: CONTRIBUTING.md

Install​

Authenticate​

Use the CLI​

Discover Commands​

Run a Query​

Format Output​

Filter Output​

Validate Before You Execute​

Example: Autonomous Data Investigation​

Build Agents with Python​

Command Reference​

Query​

Schema and Catalog​

Metadata​

Jobs​

Reflections​

Engines​

Users and Access​

Projects​

Introspection​

Global Flags​

Related Topics​

Support​