dremio — Developer CLI for Dremio Cloud

A command-line tool for working with Dremio Cloud. Run SQL queries, browse the catalog, inspect table schemas, manage reflections, monitor jobs, and audit access — from your terminal or any automation pipeline.

Built for developers who want to script against Dremio without clicking through a UI, and for AI agents that need structured access to Dremio metadata and query execution.

Dremio Cloud only. Dremio Software (self-hosted) has different auth and API behavior and is not supported in this version.

API reference: docs.dremio.com/dremio-cloud/api

Dremio Cloud has a powerful REST API and rich system tables, but no official CLI. That means:

• Debugging a slow query requires navigating the UI to find the job, then manually inspecting the profile
• Scripting catalog operations means hand-rolling curl commands with auth headers
• AI agents (Claude, GPT, etc.) need structured tool interfaces, not raw HTTP

dremio wraps all of this into a single binary with consistent output formats, input validation, and structured error handling.

• Python 3.11+ (check with python3 --version)
• A Dremio Cloud account with a project
• A Personal Access Token (PAT) — generate one from Dremio Cloud under Account Settings > Personal Access Tokens

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

# Recommended — isolated install, no venv needed
pipx install dremio-cli

# Or with uv (fast, also isolated)
uv tool install dremio-cli

# Or with pip (requires a virtual environment on modern Python)
pip install dremio-cli

# Or install from source
git clone https://github.com/dremio/cli.git
cd cli
uv tool install .

# Or for development (editable install)
uv sync

Tip: On macOS and recent Linux distros, pip install into the system Python is blocked (externally-managed-environment error). Use pipx or uv tool install instead — they automatically create an isolated environment for you.

After install, verify the binary is available:

dremio --help

There are three ways to authenticate, in order of priority:

Option A: CLI flags (highest priority — override everything)

dremio --token YOUR_PAT --project-id YOUR_PROJECT_ID query run "SELECT 1"

# EU region
dremio --uri https://api.eu.dremio.cloud --token YOUR_PAT --project-id YOUR_PROJECT_ID query run "SELECT 1"

Option B: Environment variables

export DREMIO_TOKEN=dremio_pat_xxxxxxxxxxxxx
export DREMIO_PROJECT_ID=your-project-id
# export DREMIO_URI=https://api.eu.dremio.cloud  # optional, for EU region

Option C: Config file (lowest priority)

mkdir -p ~/.config/dremioai
cat > ~/.config/dremioai/config.yaml << 'EOF'
pat: dremio_pat_xxxxxxxxxxxxx
project_id: your-project-id
# uri: https://api.dremio.cloud  # default; change for EU region
EOF
chmod 600 ~/.config/dremioai/config.yaml

Where to find these values:

• PAT: Dremio Cloud > Account Settings > Personal Access Tokens > New Token
• Project ID: Dremio Cloud > Project Settings (the UUID in the URL works too)

dremio query run "SELECT 1 AS hello"

If this returns {"job_id": "...", "state": "COMPLETED", "rowCount": 1, "rows": [{"hello": "1"}]}, you're set.

# Run a query and get results as a pretty table
dremio query run "SELECT * FROM myspace.orders LIMIT 5" --output pretty

# Search the catalog for anything matching "revenue"
dremio search "revenue"

# Create a space, then a folder inside it
dremio folder create "Analytics"
dremio folder create Analytics.reports

# Describe a table's columns
dremio schema describe myspace.analytics.monthly_revenue

# Read and update wiki docs on a table
dremio wiki get myspace.orders
dremio wiki update myspace.orders "Primary orders table. Refreshed daily from Salesforce."

# Update tags on a table
dremio tag update myspace.orders "pii,finance,daily"

# Create a raw reflection on a dataset
dremio reflection create myspace.orders --type raw
dremio reflection list myspace.orders

# Manage engines
dremio engine list
dremio engine create "analytics-engine" --size LARGE
dremio engine disable eng-abc-123

# Manage users and roles
dremio user list --output pretty
dremio role create "data-analyst"
dremio grant update projects my-project-id role role-abc "MANAGE_GRANTS,CREATE_TABLE"

# Find failed jobs from recent history
dremio job list --status FAILED --output pretty

# Audit what roles and permissions a user has
dremio user audit rahim.bhojani

# Show a conversation transcript with tool timestamps, durations, and detailed results
dremio chat history CONVERSATION_ID --show-tool-details

# Render a terminal Gantt timeline for a saved chat history dump
dremio chat gantt ./history.json --ascii --think-time

# Export one or more conversations to a standalone HTML report
dremio chat html conv-1 conv-2 -o report.html
dremio chat html -o report.html --dump-file ./history.json --dump-file ./history-2.json

Every command supports three output formats via --output / -o:

Reduce output to just the fields you need with --fields / -f. Supports dot notation for nested data:

# Only show column names and types
dremio schema describe myspace.orders --fields columns.name,columns.type

# Only show job ID and state
dremio job list --fields job_id,job_state

This is especially useful for AI agents to keep context windows small.

Discover parameters for any command programmatically:

dremio describe query.run
dremio describe reflection.list

Returns a JSON schema with parameter names, types, required/optional, and descriptions. Useful for building automation on top of dremio.

The dremio chat command group includes tools for investigating AI agent runs after the fact, both in the terminal and in a standalone HTML report.

Use --show-tool-details with one-shot chat or chat history to include:

• Tool start and finish timestamps
• Per-tool duration
• Full tool results instead of a compact done line

# One-shot chat with full tool details
dremio chat -m "who reports to Myra Richmond" --show-tool-details

# Existing conversation transcript with full tool details
dremio chat history CONVERSATION_ID --show-tool-details

Use dremio chat gantt for a saved history dump, or dremio chat history --gantt for a live conversation history.

# Render plain ASCII output
dremio chat gantt ./history.json --ascii

# Include synthetic think-time gaps between steps
dremio chat history CONVERSATION_ID --gantt --ascii --think-time

The Textual Gantt viewer adapts its foreground colors to light and dark terminal themes and uses transparent backgrounds so it blends into the terminal instead of forcing its own surface color.

Use dremio chat html to export a self-contained report with all data embedded in the page.

# Export multiple conversation IDs
dremio chat html conv-1 conv-2 conv-3 -o report.html

# Export one or more local history dumps
dremio chat html -o report.html --dump-file ./history.json --dump-file ./history-2.json

# Include think-time spans in the report
dremio chat html conv-1 -o report.html --think-time

The HTML report includes:

• An overview page with aggregate stats across all included conversations
• Mean, median, standard deviation, min, max, and totals for run time, tool time, think time, and tool durations
• Navigation from the overview page into each individual conversation timeline
• Conversation summary and result content
• Selected-span payload and tool result details

Every Dremio object has consistent CLI commands using standard CRUD verbs (list, get, create, update, delete):

space create uses SQL (CREATE SPACE) for top-level space creation. folder create uses CREATE FOLDER for all paths; single-component paths are deprecated and may fail on Space-Plugin-enabled clusters — use dremio space create instead. All other mutations use the REST API.

┌──────────────┐     ┌──────────────┐     ┌─────────────────┐
│  dremio CLI  │────▶│  client.py   │────▶│ Dremio Cloud API │
│  (typer)     │     │  (httpx)     │     │ (REST + SQL)     │
└──────────────┘     └──────────────┘     └─────────────────┘

• One HTTP layer — client.py is the only file that makes network calls. Every command goes through it.
• REST + SQL hybrid — Some operations use the REST API (catalog, reflections, access), others query system tables via SQL (jobs, reflection listing by dataset). The user doesn't need to know which.
• Async throughout — All command logic is async. The CLI wraps with asyncio.run().
• Input validation — SQL-interpolated values (job IDs, state filters) are validated before use. Catalog paths are checked for traversal attacks. This matters when AI agents are constructing commands.

All endpoints target https://api.dremio.cloud. See the Dremio Cloud API reference for full details.

Commands that query system tables (job list, job profile, reflection list, schema sample) use POST /v0/projects/{pid}/sql to submit SQL against sys.project.* tables.

dremio resolves each setting using the first match (highest priority first):

The config file also accepts the legacy dremio-mcp format (token, projectId, endpoint) for backwards compatibility.

# Custom config file
dremio --config /path/to/my/config.yaml query run "SELECT 1"

# EU region
dremio --uri https://api.eu.dremio.cloud query run "SELECT 1"

dremio ships with a Claude Code plugin that adds Dremio-aware skills to your coding sessions:

dremio is designed to be agent-friendly:

• Structured JSON output by default — no parsing needed
• dremio describe <command> lets agents self-discover parameter schemas at runtime
• --fields filtering reduces output size to fit context windows
• Input validation catches hallucinated paths, malformed UUIDs, and injection attempts before they hit the API
• Consistent error format — all API errors return {"error": "...", "status_code": N} rather than raw HTTP tracebacks

If you're building an agent that talks to Dremio, you can either shell out to dremio commands or import the async functions directly:

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()

git clone https://github.com/dremio/cli.git
cd cli
uv sync

# Run tests (no Dremio instance needed — all HTTP is mocked)
uv run pytest tests/ -v

# Run a specific test file
uv run pytest tests/test_commands/test_query.py -v

src/drs/
  cli.py           # Entry point, command group registration
  auth.py          # Config loading (env > file > defaults)
  client.py        # The single HTTP layer (all API calls)
  output.py        # JSON / CSV / pretty formatting
  utils.py         # Path parsing, input validation, error handling
  introspect.py    # Command schema registry for dremio describe
  commands/
    query.py       # run, status, cancel
    space.py       # list, get, create, delete
    folder.py      # list, get, create, delete, grants
    schema.py      # describe, lineage, sample
    wiki.py        # get, update
    tag.py         # get, update
    reflection.py  # create, list, get, refresh, delete
    job.py         # list, get, profile
    engine.py      # list, get, create, update, delete, enable, disable
    user.py        # list, get, create, delete, whoami, audit
    role.py        # list, get, create, update, delete
    grant.py       # get, update, delete
    project.py     # list, get, create, update, delete

Apache 2.0