docs: document auth command, private drivers (#263)

amoeba · ianmcook · zeroshade · web-flow · commit 1dcd3a3cb9e7 · 2026-02-10T10:59:39.000-05:00
- Adds a new guide for private drivers - Minimally links in notes about private drivers in other pages. - Adds a "since_version" badge using mkdocs-macros so we can mark things as being only available in certain releases. Closes #252 --------- Co-authored-by: Ian Cook <ianmcook@gmail.com> Co-authored-by: Matt Topol <zotthewizard@gmail.com>
diff --git a/.gitignore b/.gitignore
@@ -47,3 +47,5 @@ cdn-dev
 
 .venv
 .claude
+
+__pycache__
diff --git a/docs/concepts/driver_registry.md b/docs/concepts/driver_registry.md
@@ -16,6 +16,8 @@ limitations under the License.
 
 # Driver Registry
 
-dbc installs drivers from a "driver registry" which is an internet-accessible index of installable [ADBC driver](./driver.md) packages. Currently, dbc supports a single driver registry which is located at [https://dbc-cdn.columnar.tech](https://dbc-cdn.columnar.tech) and is managed by [Columnar](https://columnar.tech).
+dbc installs drivers from a "driver registry" which is an internet-accessible index of installable [ADBC driver](./driver.md) packages.
 
-When you run a command like [`dbc search`](../reference/cli.md#search) or [`dbc install`](../reference/cli.md#install), dbc gets information about the drivers that are available in the driver registry by downloading `index.yaml` from [https://dbc-cdn.columnar.tech](https://dbc-cdn.columnar.tech/index.yaml) or using a cached copy.
+By default, dbc is configured to communicate with Columnar's public and private driver registries. Most drivers will be from the public registry but some will be marked with a `[private]` label which means they're from the private registry. See [Private Drivers](../guides/private_drivers.md) for information on how to install and use private drivers.
+
+When you run a command like [`dbc search`](../reference/cli.md#search) or [`dbc install`](../reference/cli.md#install), dbc gets information about the drivers that are available from each configured registry by downloading its `index.yaml` or using a cached copy.
diff --git a/docs/guides/finding_drivers.md b/docs/guides/finding_drivers.md
@@ -49,6 +49,18 @@ $ dbc search sql
 • sqlite - An ADBC driver for SQLite developed under the Apache Software Foundation
 ```
 
+## Private Drivers
+
+If you are [logged in](./private_drivers.md) to a private registry, you will see some drivers marked with a `[private]` label:
+
+```console
+$ dbc search
+...
+oracle [private] An ADBC driver for Oracle Database developed by Columnar
+```
+
+These drivers can be [installed](./installing.md) and added to [driver lists](../concepts/driver_list.md) just like regular drivers.
+
 ## Options
 
 ### Verbose
diff --git a/docs/guides/private_drivers.md b/docs/guides/private_drivers.md
@@ -0,0 +1,107 @@
+<!--
+Copyright 2026 Columnar Technologies Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Private Drivers
+
+{{ since_version('v0.2.0') }}
+
+Most drivers available with dbc are hosted on Columnar's public [driver registry](../concepts/driver_registry.md). However, some of the drivers you see when you run `dbc search` may be marked with a `[private]` label.
+
+To install and use these drivers, you must:
+
+1. Log in to [Columnar Cloud](https://cloud.columnar.tech) with dbc
+2. Start a trial license
+
+Continue reading to learn how to log in and start a trial.
+
+## Logging In
+
+To log into Columnar's private driver registry, run `dbc auth login`. This will automatically create an account for you the first time you log in.
+
+You will see the following in your terminal and your default web browser will be opened:
+
+```console
+$ dbc auth login
+Opening https://auth.columnar.tech/activate?user_code=XXXX-XXXX in your default web browser...
+⠏ Waiting for confirmation...
+```
+
+In your browser, you will see a **Device Confirmation** prompt and, once you click **Confirm**, you will be redirected to log in with the provider of your choice. Once you log in, you will be redirected to [Columnar Cloud](https://cloud.columnar.tech/). Keep the tab open and continue on to the next step.
+
+## Starting a Trial
+
+To install and use a private driver, you must start a trial and obtain a license. This is a separate step from logging in.
+
+Licenses can be obtained from your [Account](https://cloud.columnar.tech/account) page on Columnar Cloud by clicking **Start Free 14-Day Trial**. Follow any instructions in the dialog that opens up and click **Accept** to create your license.
+
+### Downloading Your License
+
+dbc will automatically download your license if you:
+
+1. Have an active license
+2. Run `dbc install` with a private driver
+
+If you'd prefer to download the license manually, you can click **Download License File** and place the downloaded file in the appropriate location for your operating system:
+
+- Windows: `%LocalAppData%/dbc/credentials`
+- macOS:  `~/Library/Application Support/Columnar/dbc/credentials`
+- Linux: `~/.local/share/dbc/credentials`
+
+You may also use a custom location by setting the environment variable `XDG_DATA_HOME` to an absolute path of your choosing. If you do this, you must ensure you set the same value of `XDG_DATA_HOME` when loading drivers with the [driver manager](../concepts/driver_manager.md) for the drivers to find your license.
+
+## Logging Out
+
+To log out, run `dbc auth logout`.
+
+By default, the `logout` command doesn't purge any driver licenses from your system and only removes your login credentials. If you wish remove the local copy of your license run:
+
+```console
+$ dbc auth logout --purge
+```
+
+!!! note
+
+    Note that this command only removes the local copy of your license and does not cancel any active licenses you may have in your [Columnar Cloud](https://cloud.columnar.tech) account.
+
+!!! warning
+
+    ADBC drivers that require a license (i.e., private drivers) will stop working after you run this command. You can re-download your license with `dbc auth login`. See [Downloading Your License](#downloading-your-license).
+
+
+## API Keys
+
+dbc also supports logging in to private driver registries via API key. This is primarily intended for use in [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) systems or any system where logging in with a web browser is not possible.
+
+To create an API key, open a web browser to your [API keys](https://cloud.columnar.tech/apikeys) page.
+
+!!! note inline end
+
+    If you've already created an API key, you will see a **Create API Key** button instead.
+
+If you haven't created any API keys before, you will see a **Create Your First API Key** button. After clicking it, enter a name, optionally choose an expiration, and click **Create**. On the following screen, you will see your new API key and instructions to copy it to your clipboard.
+
+!!! note
+
+    API keys grant full access to your account so be sure to store it in a secure way.
+
+
+Then to use your API key to log in, run:
+
+```console
+$ dbc auth login --api-key "<YOUR_API_KEY_HERE>"
+```
+
+Once you've run this successfully, dbc is now logged in and you can install private drivers as you would normally.
diff --git a/docs/macros.py b/docs/macros.py
@@ -0,0 +1,28 @@
+# Copyright 2026 Columnar Technologies Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def define_env(env):
+    @env.macro
+    def since_version(version):
+        """Create a "since v1.2.3" badge for annotation features with.
+
+        Args:
+            version: git tag for version
+        """
+        return (
+            f'<span class="version-badge">'
+            f'<a href="https://github.com/columnar-tech/dbc/releases/{version}" target="_blank">SINCE {version}</a>'
+            f'</span>'
+        )
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -46,6 +46,7 @@ $ dbc [OPTIONS] <COMMAND>
 <dt><a href="#sync">dbc sync</a></dt><dd><p>Install the drivers from the <a href="../../concepts/driver_list/">driver list</a></p></dd>
 <dt><a href="#info">dbc info</a></dt><dd><p>Get information about a driver</p></dd>
 <dt><a href="#docs">dbc docs</a></dt><dd><p>Open driver documentation in a web browser</p></dd>
+<dt><a href="#auth">dbc auth</a></dt><dd><p>Manage driver registry credentials</p></dd>
 </dl>
 
 ## search
@@ -301,3 +302,52 @@ $ dbc docs <DRIVER>
 `--quiet`, `-q`
 
 :   Suppress all output
+
+## auth
+
+{{ since_version('v0.2.0') }}
+
+<h3>Usage</h3>
+
+```console
+$ dbc auth login
+$ dbc auth logout
+```
+
+<h3>Subcommands</h3>
+
+### login
+
+<h3>Arguments</h3>
+
+`REGISTRYURL`
+
+:   Optional. URL of the driver registry to authenticate with. Defaults to [https://dbc-cdn-private.columnar.tech/](https://dbc-cdn-private.columnar.tech/).
+
+<h3>Options</h3>
+
+`--clientid CLIENTID`
+
+:   OAuth Client ID (can also be set via `DBC_OAUTH_CLIENT_ID`)
+
+`--api-key API-KEY`
+
+:   Authenticate using an API key instead of OAuth (use '-' to read from stdin)
+
+### logout
+
+<h3>Arguments</h3>
+
+`REGISTRYURL`
+
+:   Optional. URL of the driver registry to log out from. Defaults to [https://dbc-cdn-private.columnar.tech/](https://dbc-cdn-private.columnar.tech/).
+
+<h3>Options</h3>
+
+`--purge`
+
+:   Remove all local auth credentials for dbc
+
+    !!! warning
+
+        ADBC drivers that require a license (i.e., private drivers) will stop working after you run this command. You can re-download your license with `dbc auth login`. See [Downloading Your License](../guides/private_drivers.md#downloading-your-license).
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -2,6 +2,35 @@
   --md-default-bg-color: rgb(33, 33, 33);
   --md-code-bg-color: rgb(45, 45, 45);
 }
+
+/* since_version badge styling. see macros.py */
+.version-badge {
+  background: var(--md-accent-fg-color);
+  color: var(--md-accent-bg-color);
+  padding: 2px 6px;
+  border-radius: 3px;
+  font-size: 0.75em;
+  font-weight: bold;
+  display: inline-block;
+}
+
+.version-badge a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.version-badge a:hover {
+  color: inherit;
+  text-decoration: underline;
+}
+
+/* Disable highlighting for shell built-ins. This means words in console blocks
+like echo, export, logout, and source will use the same color as other commands
+and won't show up highlighted as purple. */
+.highlight .nb {
+  color: inherit;
+}
+
 /* Hide the site name in the header... */
 .md-header__title .md-header__topic:first-of-type {
   display: none !important;
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -46,6 +46,7 @@ nav:
       - Using a Driver List: guides/driver_list.md
       - Driver Managers: guides/driver_manager.md
       - Python Notebooks: guides/python_notebooks.md
+      - Private Drivers: guides/private_drivers.md
   - Concepts:
       - concepts/index.md
       - Driver: concepts/driver.md
@@ -119,6 +120,8 @@ exclude_docs: |
 extra_javascript:
   - scripts/extra.js
 plugins:
+  - macros:
+      module_name: docs/macros
   - privacy
   - search
   - social:
diff --git a/pixi.lock b/pixi.lock
diff --git a/pixi.toml b/pixi.toml

-Original file line number
+Diff line change
 .venv
 .claude
++
 +__pycache__