docs: add pb CLI documentation

content/docs/meta.json

@@ -47,6 +47,15 @@
     "user-guide/retention",
     "user-guide/smart-cache",
     "api",
+    "---pb CLI---",
+    "pb-cli/index",
+    "pb-cli/install",
+    "pb-cli/connect",
+    "pb-cli/query",
+    "pb-cli/promql",
+    "pb-cli/tail",
+    "pb-cli/datasets",
+    "pb-cli/admin",
     "---Self Hosted---",
     "self-hosted/installation",
     "self-hosted/configuration",

content/docs/pb-cli/admin.mdx

@@ -0,0 +1,95 @@
+---
+title: "Users and Roles"
+description: "Manage users and role-based access control with pb user and pb role."
+---
+
+<Callout type="info">
+These commands require admin privileges on the Parseable server.
+</Callout>
+
+Parseable uses role-based access control (RBAC). Roles define what a user can do on which datasets. You create roles first, then assign them to users.
+
+## Roles
+
+### Create a role
+
+```bash
+pb role add <name>
+```
+
+This starts an interactive prompt where you choose a privilege level and the dataset it applies to.
+
+**Privilege levels:**
+
+| Privilege | Access |
+|---|---|
+| `reader` | Read-only access to a specific dataset |
+| `writer` | Read and write access to a specific dataset |
+| `ingestor` | Write-only (ingest) access to a specific dataset |
+| `admin` | Full system-wide access |
+
+```bash
+pb role add log-readers
+# → select privilege: reader
+# → select dataset: backend_logs
+```
+
+### List roles
+
+```bash
+pb role list
+
+# JSON output
+pb role list --output json
+```
+
+### Delete a role
+
+```bash
+pb role remove <name>
+```
+
+## Users
+
+### Create a user
+
+```bash
+pb user add <username>
+```
+
+The server generates a password and prints it. Save it — it cannot be retrieved later.
+
+```bash
+# Create a user and assign roles immediately
+pb user add bob --role log-readers,developers
+```
+
+### List users
+
+```bash
+pb user list
+
+# JSON output
+pb user list --output json
+```
+
+### Update user roles
+
+```bash
+pb user set-role <username> <roles>
+```
+
+```bash
+# Assign (or replace) roles
+pb user set-role bob log-readers,admins
+```
+
+### Delete a user
+
+```bash
+pb user remove <username>
+```
+
+<Callout type="warn">
+Roles must exist before they can be assigned to a user. Create roles with `pb role add` first.
+</Callout>

content/docs/pb-cli/connect.mdx

@@ -0,0 +1,91 @@
+---
+title: "Connecting to a Server"
+description: "Create a profile and authenticate with your Parseable instance."
+---
+
+`pb` stores server connections as named **profiles**. A profile holds the server URL and credentials for one Parseable instance. You can have multiple profiles and switch between them, useful when working with separate staging and production deployments.
+
+## Interactive login (recommended)
+
+Run `pb login` to start the interactive wizard. It walks you through selecting a server type, entering your URL, choosing an authentication method, and saving the profile.
+
+```bash
+pb login
+```
+
+The wizard prompts you for:
+- Server type (self-hosted or cloud)
+- Server URL (e.g. `https://logs.mycompany.com`)
+- Auth method — username/password or API key
+- Credentials
+- Profile name (defaults to `default`)
+
+Once complete, the profile is saved and set as the active default.
+
+## Non-interactive login
+
+For scripts and CI pipelines, use `pb profile add` to create a profile without prompts:
+
+```bash
+pb profile add <name> <url> <username> <password>
+```
+
+```bash
+# Example
+pb profile add production https://logs.mycompany.com admin s3cr3t
+
+# With an API key instead of username/password
+pb profile add ci https://logs.mycompany.com --token myapikey
+```
+
+## Managing profiles
+
+```bash
+# List all saved profiles
+pb profile list
+
+# Switch the active default profile
+pb profile default staging
+
+# Update a profile's server URL
+pb profile update production https://new-url.mycompany.com
+
+# Remove a profile
+pb profile remove old-staging
+```
+
+## Check connection status
+
+```bash
+pb status
+```
+
+This validates that the active profile can reach the server and shows the server version:
+
+```
+Profile : production
+URL     : https://logs.mycompany.com
+User    : admin
+Status  : ✓ Connected  (server v1.4.2)
+```
+
+## Logout
+
+```bash
+pb logout
+```
+
+Removes credentials from the active profile. To log out of a specific profile, switch to it first with `pb profile default <name>`, then run `pb logout`.
+
+## Config file location
+
+Profiles are stored in a TOML config file on disk:
+
+| Platform | Path |
+|---|---|
+| macOS / Linux | `~/.config/pb/config.toml` |
+| Windows | `%AppData%\pb\config.toml` |
+
+<Callout type="info">
+All commands use the active default profile automatically. Use `pb profile default <name>` to switch between servers without specifying a profile on every command.
+</Callout>

content/docs/pb-cli/datasets.mdx

@@ -0,0 +1,68 @@
+---
+title: "Dataset Management"
+description: "Create, inspect, and delete datasets with pb dataset."
+---
+
+Datasets are the top-level containers for log and metrics data in Parseable. Use the `pb dataset` subcommands to manage them from the terminal.
+
+## List datasets
+
+```bash
+pb dataset list
+```
+
+Shows all datasets available on the active server.
+
+```bash
+# JSON output for scripting
+pb dataset list --output json
+```
+
+## Create a dataset
+
+```bash
+pb dataset add <name>
+```
+
+```bash
+pb dataset add backend_logs
+pb dataset add otel_metrics
+```
+
+Dataset names must be lowercase and contain no spaces.
+
+## Inspect a dataset
+
+```bash
+pb dataset info <name>
+```
+
+```bash
+pb dataset info backend_logs
+```
+
+Shows:
+- Event count and ingestion size
+- Storage size and compression ratio
+- Retention period (if configured)
+- Active alerts (if any)
+- Dataset type (logs or metrics)
+
+```bash
+# JSON output
+pb dataset info backend_logs --output json
+```
+
+## Delete a dataset
+
+```bash
+pb dataset remove <name>
+```
+
+```bash
+pb dataset remove old_logs
+```
+
+<Callout type="warn">
+Deleting a dataset removes all data it contains. This action cannot be undone.
+</Callout>

content/docs/pb-cli/index.mdx

@@ -0,0 +1,60 @@
+---
+title: pb CLI
+description: A command-line interface for Parseable that lets you query logs, analyze metrics, and stream live events directly from your terminal.
+---
+
+`pb` is the official CLI for Parseable. It provides a terminal-based interface for querying log datasets with SQL, running PromQL queries on metrics, streaming live events, and managing datasets, users, and roles without opening a browser.
+
+`pb` is built for developers who work in the terminal and want full access to Parseable from shell scripts, CI pipelines, or day-to-day workflows. It supports both a standard command-line mode for scripting and automation, and a full-screen interactive TUI for exploratory work.
+
+> Currently, `pb` works with self-hosted Parseable deployments only. Cloud support is coming soon.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `pb login` | Start an interactive wizard to connect to a Parseable server and save the connection as a profile |
+| `pb profile` | List, switch, update, and remove saved server connections |
+| `pb status` | Verify the active connection and display server version information |
+| `pb query run` | Execute SQL queries against a log dataset, with support for time ranges, JSON output, and interactive TUI mode |
+| `pb query promql` | Run PromQL range and instant queries on a metrics dataset, with label exploration and cardinality analysis |
+| `pb tail` | Stream live log events from a dataset in real time as newline-delimited JSON |
+| `pb dataset` | List, create, inspect, and delete datasets on the connected server |
+| `pb user` | Create users, assign roles, and manage user access |
+| `pb role` | Define roles with specific privilege levels and dataset scopes |
+
+## Interactive mode
+
+Both SQL log queries and PromQL metrics queries support an interactive full-screen TUI using the `-i` flag. In this mode, `pb` opens a panel-based interface where you can write and edit your query, adjust the time range, and browse through paginated results this all without leaving the terminal.
+
+```bash
+# Open the interactive SQL query interface
+pb query run -i
+
+# Open the interactive PromQL interface
+pb query run -i --promql
+#or
+pb query promql run -i
+```
+
+Navigate between panels using `Tab` and `Shift+Tab`. Press `Ctrl+R` to run the query. Results are displayed in a scrollable table with column navigation and inline row filtering.
+
+## Output formats
+
+Every `pb` command that returns data supports `--output json` for machine-readable output. The default output is a human-readable table.
+
+```bash
+# Human-readable table (default)
+pb dataset list
+
+# JSON output for scripting or piping to jq
+pb dataset list --output json
+pb query run "SELECT level, count(*) FROM logs GROUP BY level" --from 1h --output json
+```
+
+## Getting started
+
+1. [Install pb](/docs/pb-cli/install) — download the binary for macOS, Linux, or Windows
+2. [Connect to a server](/docs/pb-cli/connect) — authenticate and save a server profile
+3. [Run a SQL query](/docs/pb-cli/query) — query a log dataset with a time range
+4. [Run a PromQL query](/docs/pb-cli/promql) — query a metrics dataset