From 7481147a83794f6b1d0292c128287bd7a6620014 Mon Sep 17 00:00:00 2001
From: Aniket Kulkarni <aniket.kulkarni@dremio.com>
Date: Wed, 25 Mar 2026 18:37:23 -0400
Subject: [PATCH] docs: improve install discoverability and recommend pipx/uv
 over bare pip

A non-dev user tried installing via Claude Code and hit three issues:
1. Claude found `dremio-client` (wrong package) instead of `dremio-cli`
2. `pip install` failed with `externally-managed-environment` on modern macOS
3. PATH wasn't configured for `~/.local/bin`

Changes:
- Lead install instructions with `pipx`/`uv tool install` (isolated by default)
- Add explicit note that `dremio-client` is a different, unrelated package
- Add tip explaining the `externally-managed-environment` error
- Update PyPI description to include install command for LLM discoverability
- Add `dremio-cloud` and `official` keywords to pyproject.toml

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md      | 15 ++++++++++++---
 pyproject.toml |  4 ++--
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 8cd782a..634b402 100644
--- a/README.md
+++ b/README.md
@@ -32,13 +32,18 @@ Dremio Cloud has a powerful REST API and rich system tables, but no official CLI
 
 ### 1. Install
 
+The package name is **`dremio-cli`** (not `dremio-client`, which is an unrelated third-party package).
+
 ```bash
-# Install from PyPI (recommended)
-pip install dremio-cli
+# Recommended — isolated install, no venv needed
+pipx install dremio-cli
 
-# Or with uv
+# 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
@@ -48,6 +53,10 @@ uv tool 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:
 
 ```bash
diff --git a/pyproject.toml b/pyproject.toml
index a130038..bca0a9c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,7 +1,7 @@
 [project]
 name = "dremio-cli"
 dynamic = ["version"]
-description = "Developer CLI for Dremio Cloud"
+description = "Official developer CLI for Dremio Cloud — install with: pipx install dremio-cli"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
@@ -17,7 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Topic :: Database",
 ]
-keywords = ["dremio", "cli", "data-lake", "sql"]
+keywords = ["dremio", "dremio-cloud", "cli", "data-lake", "sql", "official"]
 dependencies = [
     "typer>=0.9",
     "httpx>=0.27",