From 6087f42b8b003ae31571339a227037e3803b5d2c Mon Sep 17 00:00:00 2001 From: Pratik Date: Fri, 15 May 2026 17:27:36 +0530 Subject: [PATCH 1/2] docs: add pb CLI documentation --- content/docs/meta.json | 9 +++ content/docs/pb-cli/admin.mdx | 95 ++++++++++++++++++++++++++++++++ content/docs/pb-cli/connect.mdx | 91 ++++++++++++++++++++++++++++++ content/docs/pb-cli/datasets.mdx | 68 +++++++++++++++++++++++ content/docs/pb-cli/index.mdx | 60 ++++++++++++++++++++ content/docs/pb-cli/install.mdx | 92 +++++++++++++++++++++++++++++++ content/docs/pb-cli/meta.json | 15 +++++ content/docs/pb-cli/promql.mdx | 85 ++++++++++++++++++++++++++++ content/docs/pb-cli/query.mdx | 82 +++++++++++++++++++++++++++ content/docs/pb-cli/tail.mdx | 72 ++++++++++++++++++++++++ 10 files changed, 669 insertions(+) create mode 100644 content/docs/pb-cli/admin.mdx create mode 100644 content/docs/pb-cli/connect.mdx create mode 100644 content/docs/pb-cli/datasets.mdx create mode 100644 content/docs/pb-cli/index.mdx create mode 100644 content/docs/pb-cli/install.mdx create mode 100644 content/docs/pb-cli/meta.json create mode 100644 content/docs/pb-cli/promql.mdx create mode 100644 content/docs/pb-cli/query.mdx create mode 100644 content/docs/pb-cli/tail.mdx diff --git a/content/docs/meta.json b/content/docs/meta.json index 11eceb3..08ef7a8 100644 --- a/content/docs/meta.json +++ b/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", diff --git a/content/docs/pb-cli/admin.mdx b/content/docs/pb-cli/admin.mdx new file mode 100644 index 0000000..1b38b67 --- /dev/null +++ b/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." +--- + + +These commands require admin privileges on the Parseable server. + + +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 +``` + +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 +``` + +## Users + +### Create a user + +```bash +pb user add +``` + +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 +``` + +```bash +# Assign (or replace) roles +pb user set-role bob log-readers,admins +``` + +### Delete a user + +```bash +pb user remove +``` + + +Roles must exist before they can be assigned to a user. Create roles with `pb role add` first. + diff --git a/content/docs/pb-cli/connect.mdx b/content/docs/pb-cli/connect.mdx new file mode 100644 index 0000000..a416a86 --- /dev/null +++ b/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 +``` + +```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 `, 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` | + + +All commands use the active default profile automatically. Use `pb profile default ` to switch between servers without specifying a profile on every command. + diff --git a/content/docs/pb-cli/datasets.mdx b/content/docs/pb-cli/datasets.mdx new file mode 100644 index 0000000..5d993fa --- /dev/null +++ b/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 +``` + +```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 +``` + +```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 +``` + +```bash +pb dataset remove old_logs +``` + + +Deleting a dataset removes all data it contains. This action cannot be undone. + diff --git a/content/docs/pb-cli/index.mdx b/content/docs/pb-cli/index.mdx new file mode 100644 index 0000000..aa135a4 --- /dev/null +++ b/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 diff --git a/content/docs/pb-cli/install.mdx b/content/docs/pb-cli/install.mdx new file mode 100644 index 0000000..fb91c2a --- /dev/null +++ b/content/docs/pb-cli/install.mdx @@ -0,0 +1,92 @@ +--- +title: "Installation" +description: "Download and install pb on macOS, Linux, or Windows." +--- + +## macOS + +First, check which chip your Mac has. Click the Apple menu → **About This Mac**. + +- If it says **Apple M1 / M2 / M3** → use the `arm64` binary +- If it says **Intel** → use the `amd64` binary + +```bash +# Apple Silicon (M1, M2, M3) +curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_darwin_arm64 +chmod +x pb_darwin_arm64 +sudo mv pb_darwin_arm64 /usr/local/bin/pb +``` + +```bash +# Intel +curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_darwin_amd64 +chmod +x pb_darwin_amd64 +sudo mv pb_darwin_amd64 /usr/local/bin/pb +``` + +## Linux + +Not sure which architecture your machine is? Run `uname -m` in your terminal. + +- `x86_64` → use `amd64` +- `aarch64` → use `arm64` + +```bash +# x86 64-bit (amd64) +curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_linux_amd64 +chmod +x pb_linux_amd64 +sudo mv pb_linux_amd64 /usr/local/bin/pb +``` + +```bash +# ARM 64-bit (arm64) +curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_linux_arm64 +chmod +x pb_linux_arm64 +sudo mv pb_linux_arm64 /usr/local/bin/pb +``` + +## Windows + +Download `pb_windows_amd64` from the [releases page](https://github.com/parseablehq/pb/releases), rename it to `pb.exe`, and move it to a folder that is in your system `PATH`. + +## Using Go + +If you have Go 1.21 or later installed, you can install `pb` directly with: + +```bash +go install github.com/parseablehq/pb@latest +``` + +This builds `pb` from source and places it in your `$GOPATH/bin`. Make sure `$GOPATH/bin` is in your `PATH`. + +## Verify installation + +After installing, run: + +```bash +pb --version +``` + +You should see the version number and build commit printed to the terminal. If you get a `command not found` error, check that the folder where `pb` was moved is included in your `PATH`. + +## Shell autocomplete + +`pb` can generate completion scripts so your shell auto-completes commands and flags. Run this once after installation. + +**bash** +```bash +pb autocomplete bash > /etc/bash_completion.d/pb +source /etc/bash_completion.d/pb +``` + +**zsh** +```bash +pb autocomplete zsh > /usr/local/share/zsh/site-functions/_pb +autoload -Uz compinit && compinit +``` + +**PowerShell** +```powershell +pb autocomplete powershell > $env:USERPROFILE\Documents\PowerShell\pb_complete.ps1 +. $env:USERPROFILE\Documents\PowerShell\pb_complete.ps1 +``` diff --git a/content/docs/pb-cli/meta.json b/content/docs/pb-cli/meta.json new file mode 100644 index 0000000..42a65e8 --- /dev/null +++ b/content/docs/pb-cli/meta.json @@ -0,0 +1,15 @@ +{ + "title": "pb CLI", + "description": "Command-line interface for Parseable", + "defaultOpen": true, + "pages": [ + "index", + "install", + "connect", + "query", + "promql", + "tail", + "datasets", + "admin" + ] +} diff --git a/content/docs/pb-cli/promql.mdx b/content/docs/pb-cli/promql.mdx new file mode 100644 index 0000000..1af9b6b --- /dev/null +++ b/content/docs/pb-cli/promql.mdx @@ -0,0 +1,85 @@ +--- +title: "PromQL Queries" +description: "Query metrics datasets in Parseable using PromQL." +--- + +Parseable can store metrics data ingested via OpenTelemetry or Prometheus remote write. The `pb query promql` subcommands let you query, explore, and analyze those metrics from the terminal. + +## Run a PromQL query + +```bash +pb query promql run "" --dataset --from +``` + +```bash +# Range query: rate of HTTP requests over the last hour, 1-minute resolution +pb query promql run "rate(http_requests_total[5m])" --dataset otel_metrics --from 1h --step 1m + +# Instant query: current value only +pb query promql run "up" --dataset otel_metrics --instant +``` + +### Flags + +| Flag | Default | Description | +|---|---|---| +| `--dataset` / `-d` | — | Metrics dataset to query (required) | +| `--from` / `-f` | `5m` | Start of query window | +| `--to` / `-t` | `now` | End of query window | +| `--step` | `1m` | Resolution step for range queries | +| `--instant` | false | Run as instant query instead of range | +| `--output` / `-o` | `text` | Output format: `text` or `json` | +| `--interactive` / `-i` | false | Open interactive TUI | + +## Interactive TUI + +```bash +pb query promql run -i +``` + +The TUI has panels for Dataset, Query expression, Time Range, Step size, and Results. Navigate with `Tab` / `Shift+Tab`, run with `Ctrl+R`. + +## Explore labels and series + +```bash +# List all label names in a metrics dataset +pb query promql labels --dataset otel_metrics + +# List all values for a specific label +pb query promql label-values job --dataset otel_metrics + +# Find series matching a selector +pb query promql series --match 'http_requests_total' --dataset otel_metrics +pb query promql series --match '{job="api-server"}' --dataset otel_metrics +``` + +## Cardinality analysis + +High cardinality labels are a common cause of performance issues. These commands help you find them. + +```bash +# Labels with the most distinct values +pb query promql cardinality label-names --dataset otel_metrics --limit 20 + +# Series count per value for a specific label +pb query promql cardinality label-values --label job --dataset otel_metrics + +# Currently active series +pb query promql cardinality active-series --dataset otel_metrics --selector '{job="api"}' +``` + +## TSDB statistics + +```bash +pb query promql tsdb --dataset otel_metrics --top 10 +``` + +Shows storage statistics for the metrics dataset, broken down by the top N series by size. + +## Active queries + +```bash +pb query promql active-queries +``` + +Lists any PromQL queries currently running on the server. Useful for debugging slow or stuck queries. diff --git a/content/docs/pb-cli/query.mdx b/content/docs/pb-cli/query.mdx new file mode 100644 index 0000000..944d388 --- /dev/null +++ b/content/docs/pb-cli/query.mdx @@ -0,0 +1,82 @@ +--- +title: "SQL Queries" +description: "Run SQL queries against your log datasets using pb query run." +--- + +`pb query run` lets you query any dataset with SQL. You can specify a time range, save queries for reuse, and open an interactive TUI for exploratory work. + +## Basic usage + +```bash +pb query run "SELECT * FROM backend" --from 10m --to now +``` + +`--from` and `--to` define the time window to query. The dataset name is the SQL `FROM` target. + +## Time range syntax + +| Format | Example | Meaning | +|---|---|---| +| Relative | `10m`, `2h`, `7d` | Last N minutes / hours / days | +| Absolute | `2024-01-15T00:00:00Z` | Exact RFC3339 timestamp | +| Keyword | `now` | Current time | + +```bash +# Last 30 minutes +pb query run "SELECT * FROM logs LIMIT 100" --from 30m + +# Specific time window +pb query run "SELECT count(*) FROM logs" --from 2024-01-01T00:00:00Z --to 2024-01-02T00:00:00Z + +# Default: last 1 minute +pb query run "SELECT * FROM logs" +``` + +## JSON output + +Use `--output json` to get structured output suitable for scripting: + +```bash +pb query run "SELECT * FROM logs LIMIT 50" --from 1h --output json +``` + +## Save and reuse queries + +Save a query for later with `--save-as`: + +```bash +pb query run "SELECT level, count(*) FROM logs GROUP BY level" --from 1h --save-as error-summary +``` + +List and manage saved queries: + +```bash +pb query list +``` + +This opens an interactive menu where you can apply or delete saved queries. + +## Interactive TUI mode + +Add `-i` to open the full-screen interactive query interface: + +```bash +pb query run -i +``` + +The TUI has three panels - Query, Time Range, and Results Table. Navigate between them with `Tab` / `Shift+Tab`. + +| Key | Action | +|---|---| +| `Tab` / `Shift+Tab` | Switch between panels | +| `Ctrl+R` | Run query | +| `↑` / `↓` | Scroll rows | +| `Shift+↑` / `Shift+↓` | Page up / down | +| `←` / `→` | Scroll columns | +| `/` | Filter table rows | +| `Esc` | Clear filter | +| `Ctrl+B` | Previous page of results | + + +Field names containing dots (OTel convention, e.g. `service.name`) or hyphens are automatically quoted in queries. You don't need to add quotes manually. + diff --git a/content/docs/pb-cli/tail.mdx b/content/docs/pb-cli/tail.mdx new file mode 100644 index 0000000..1e67c58 --- /dev/null +++ b/content/docs/pb-cli/tail.mdx @@ -0,0 +1,72 @@ +--- +title: "Live Tail" +description: "Stream log events from a dataset in real time with pb tail." +--- + +`pb tail` connects to a dataset and streams new events as they arrive. It is designed for real-time monitoring, watching an ingestion pipeline, debugging a running service, or confirming that data is flowing. + +## Usage + +```bash +pb tail +``` + +```bash +# Watch a dataset called "backend" +pb tail backend +``` + +Events are printed as newline-delimited JSON, one event per line. Press `Ctrl+C` to stop. + +``` +● watching backend... (ctrl+c to stop) +{"level":"info","msg":"request received","service":"api","ts":"2024-01-15T10:23:01Z"} +{"level":"error","msg":"db timeout","service":"api","ts":"2024-01-15T10:23:02Z"} +``` + +## Piping to jq + +Because output is newline-delimited JSON, you can pipe directly to `jq` for filtering and formatting: + +```bash +# Pretty-print all events +pb tail backend | jq . + +# Show only error-level events +pb tail backend | jq 'select(.level == "error")' + +# Extract specific fields +pb tail backend | jq '{time: .ts, msg: .msg}' +``` + +## Piping to grep + +```bash +# Show only lines containing "timeout" +pb tail backend | grep timeout + +# Exclude health check noise +pb tail backend | grep -v "health_check" +``` + +## How it works + +`pb tail` uses Apache Arrow Flight over gRPC for streaming. This means it needs access to **two ports** on your Parseable server, not just the main HTTP port: + +| Port | Protocol | Purpose | +|---|---|---| +| `8000` | HTTP | Main Parseable API (login, query, datasets) | +| `8001` | gRPC | Arrow Flight streaming (used by `pb tail`) | + +## Troubleshooting + +**Error: `rpc error: code = Unavailable ... dial tcp :8001: i/o timeout`** + +This means `pb tail` connected to the server successfully over HTTP, but could not reach the gRPC port on `8001`. This is the most common error when using `pb tail`. + +Possible causes: +- Port `8001` is blocked by a firewall on the server +- Port `8001` is not exposed in your Docker or Kubernetes setup +- Your network restricts outbound gRPC connections + +To fix it, make sure port `8001` is open and reachable from your machine. If you are running Parseable in Docker, add `-p 8001:8001` to your run command. If you are behind a firewall, allow outbound TCP on port `8001`. From 13b6bb967deb793c9e94fe602b7289bfe7ada38b Mon Sep 17 00:00:00 2001 From: Pratik Date: Sat, 16 May 2026 13:30:22 +0530 Subject: [PATCH 2/2] feat: add fumadocs style for pb --- app/(docs)/layout.tsx | 38 +++++------- content/docs/meta.json | 9 --- content/docs/pb-cli/admin.mdx | 48 +++++++++----- content/docs/pb-cli/connect.mdx | 22 ++++--- content/docs/pb-cli/datasets.mdx | 50 +++++++++------ content/docs/pb-cli/index.mdx | 25 +++++--- content/docs/pb-cli/install.mdx | 103 +++++++++++++++++++------------ content/docs/pb-cli/meta.json | 2 + content/docs/pb-cli/promql.mdx | 49 +++++++++++---- content/docs/pb-cli/query.mdx | 36 ++++++++--- mdx-components.tsx | 3 + 11 files changed, 239 insertions(+), 146 deletions(-) diff --git a/app/(docs)/layout.tsx b/app/(docs)/layout.tsx index 14aa98b..01d2be9 100644 --- a/app/(docs)/layout.tsx +++ b/app/(docs)/layout.tsx @@ -4,11 +4,12 @@ import { baseOptions } from '@/app/layout.config'; import { source } from '@/lib/source'; import SearchButton from '@/components/SearchButton'; import { AskAITrigger } from '@/components/AskAI'; +import { BookOpen, Terminal } from 'lucide-react'; export default function Layout({ children }: { children: ReactNode }) { return ( - - {node.icon} - - ), - }; + tabs: [ + { + title: 'Parseable', + description: 'Docs & Guides', + url: '/docs', + icon: , }, - }, + { + title: 'pb CLI', + description: 'Command-line interface', + url: '/docs/pb-cli', + icon: , + }, + ], }} > {children} diff --git a/content/docs/meta.json b/content/docs/meta.json index 08ef7a8..11eceb3 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -47,15 +47,6 @@ "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", diff --git a/content/docs/pb-cli/admin.mdx b/content/docs/pb-cli/admin.mdx index 1b38b67..06d66b5 100644 --- a/content/docs/pb-cli/admin.mdx +++ b/content/docs/pb-cli/admin.mdx @@ -30,18 +30,26 @@ This starts an interactive prompt where you choose a privilege level and the dat ```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 -``` + ```bash + pb role list + ``` + + + + + ```bash + pb role list --output json + ``` + + + ### Delete a role @@ -59,19 +67,30 @@ pb user add The server generates a password and prints it. Save it — it cannot be retrieved later. +Assign roles at creation time: + ```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 -``` + ```bash + pb user list + ``` + + + + + ```bash + pb user list --output json + ``` + + + ### Update user roles @@ -80,7 +99,6 @@ pb user set-role ``` ```bash -# Assign (or replace) roles pb user set-role bob log-readers,admins ``` @@ -92,4 +110,4 @@ pb user remove Roles must exist before they can be assigned to a user. Create roles with `pb role add` first. - + \ No newline at end of file diff --git a/content/docs/pb-cli/connect.mdx b/content/docs/pb-cli/connect.mdx index a416a86..df8b0e1 100644 --- a/content/docs/pb-cli/connect.mdx +++ b/content/docs/pb-cli/connect.mdx @@ -30,27 +30,31 @@ For scripts and CI pipelines, use `pb profile add` to create a profile without p pb profile add ``` +With username and password: + ```bash -# Example pb profile add production https://logs.mycompany.com admin s3cr3t +``` + +With an API key: -# With an API key instead of username/password +```bash pb profile add ci https://logs.mycompany.com --token myapikey ``` ## Managing profiles +List and switch 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 +Update or remove a profile: -# Remove a profile +```bash +pb profile update production https://new-url.mycompany.com pb profile remove old-staging ``` @@ -88,4 +92,4 @@ Profiles are stored in a TOML config file on disk: All commands use the active default profile automatically. Use `pb profile default ` to switch between servers without specifying a profile on every command. - + \ No newline at end of file diff --git a/content/docs/pb-cli/datasets.mdx b/content/docs/pb-cli/datasets.mdx index 5d993fa..9ac1158 100644 --- a/content/docs/pb-cli/datasets.mdx +++ b/content/docs/pb-cli/datasets.mdx @@ -7,16 +7,22 @@ Datasets are the top-level containers for log and metrics data in Parseable. Use ## List datasets -```bash -pb dataset list -``` + + -Shows all datasets available on the active server. + ```bash + pb dataset list + ``` -```bash -# JSON output for scripting -pb dataset list --output json -``` + + + + ```bash + pb dataset list --output json + ``` + + + ## Create a dataset @@ -33,13 +39,22 @@ Dataset names must be lowercase and contain no spaces. ## Inspect a dataset -```bash -pb dataset info -``` + + -```bash -pb dataset info backend_logs -``` + ```bash + pb dataset info backend_logs + ``` + + + + + ```bash + pb dataset info backend_logs --output json + ``` + + + Shows: - Event count and ingestion size @@ -48,11 +63,6 @@ Shows: - Active alerts (if any) - Dataset type (logs or metrics) -```bash -# JSON output -pb dataset info backend_logs --output json -``` - ## Delete a dataset ```bash @@ -65,4 +75,4 @@ pb dataset remove old_logs Deleting a dataset removes all data it contains. This action cannot be undone. - + \ No newline at end of file diff --git a/content/docs/pb-cli/index.mdx b/content/docs/pb-cli/index.mdx index aa135a4..8ce441d 100644 --- a/content/docs/pb-cli/index.mdx +++ b/content/docs/pb-cli/index.mdx @@ -7,7 +7,7 @@ description: A command-line interface for Parseable that lets you query logs, an `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. +Currently, `pb` works with self-hosted Parseable deployments only. Cloud support is coming soon. ## Commands @@ -27,15 +27,22 @@ description: A command-line interface for Parseable that lets you query logs, an 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 -``` + ```bash + pb query run -i + ``` + + + + + ```bash + pb query run -i --promql + ``` + + + 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. diff --git a/content/docs/pb-cli/install.mdx b/content/docs/pb-cli/install.mdx index fb91c2a..14b6116 100644 --- a/content/docs/pb-cli/install.mdx +++ b/content/docs/pb-cli/install.mdx @@ -7,22 +7,29 @@ description: "Download and install pb on macOS, Linux, or Windows." First, check which chip your Mac has. Click the Apple menu → **About This Mac**. -- If it says **Apple M1 / M2 / M3** → use the `arm64` binary +- If it says **Apple Silicon** → use the `arm64` binary - If it says **Intel** → use the `amd64` binary -```bash -# Apple Silicon (M1, M2, M3) -curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_darwin_arm64 -chmod +x pb_darwin_arm64 -sudo mv pb_darwin_arm64 /usr/local/bin/pb -``` + + -```bash -# Intel -curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_darwin_amd64 -chmod +x pb_darwin_amd64 -sudo mv pb_darwin_amd64 /usr/local/bin/pb -``` + ```bash + curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_darwin_arm64 + chmod +x pb_darwin_arm64 + sudo mv pb_darwin_arm64 /usr/local/bin/pb + ``` + + + + + ```bash + curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_darwin_amd64 + chmod +x pb_darwin_amd64 + sudo mv pb_darwin_amd64 /usr/local/bin/pb + ``` + + + ## Linux @@ -31,19 +38,26 @@ Not sure which architecture your machine is? Run `uname -m` in your terminal. - `x86_64` → use `amd64` - `aarch64` → use `arm64` -```bash -# x86 64-bit (amd64) -curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_linux_amd64 -chmod +x pb_linux_amd64 -sudo mv pb_linux_amd64 /usr/local/bin/pb -``` + + -```bash -# ARM 64-bit (arm64) -curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_linux_arm64 -chmod +x pb_linux_arm64 -sudo mv pb_linux_arm64 /usr/local/bin/pb -``` + ```bash + curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_linux_amd64 + chmod +x pb_linux_amd64 + sudo mv pb_linux_amd64 /usr/local/bin/pb + ``` + + + + + ```bash + curl -LO https://github.com/parseablehq/pb/releases/latest/download/pb_linux_arm64 + chmod +x pb_linux_arm64 + sudo mv pb_linux_arm64 /usr/local/bin/pb + ``` + + + ## Windows @@ -73,20 +87,29 @@ You should see the version number and build commit printed to the terminal. If y `pb` can generate completion scripts so your shell auto-completes commands and flags. Run this once after installation. -**bash** -```bash -pb autocomplete bash > /etc/bash_completion.d/pb -source /etc/bash_completion.d/pb -``` + + -**zsh** -```bash -pb autocomplete zsh > /usr/local/share/zsh/site-functions/_pb -autoload -Uz compinit && compinit -``` + ```bash + pb autocomplete bash > /etc/bash_completion.d/pb + source /etc/bash_completion.d/pb + ``` -**PowerShell** -```powershell -pb autocomplete powershell > $env:USERPROFILE\Documents\PowerShell\pb_complete.ps1 -. $env:USERPROFILE\Documents\PowerShell\pb_complete.ps1 -``` + + + + ```bash + pb autocomplete zsh > /usr/local/share/zsh/site-functions/_pb + autoload -Uz compinit && compinit + ``` + + + + + ```powershell + pb autocomplete powershell > $env:USERPROFILE\Documents\PowerShell\pb_complete.ps1 + . $env:USERPROFILE\Documents\PowerShell\pb_complete.ps1 + ``` + + + \ No newline at end of file diff --git a/content/docs/pb-cli/meta.json b/content/docs/pb-cli/meta.json index 42a65e8..16c2c5e 100644 --- a/content/docs/pb-cli/meta.json +++ b/content/docs/pb-cli/meta.json @@ -1,6 +1,8 @@ { "title": "pb CLI", "description": "Command-line interface for Parseable", + "root": true, + "icon": "Terminal", "defaultOpen": true, "pages": [ "index", diff --git a/content/docs/pb-cli/promql.mdx b/content/docs/pb-cli/promql.mdx index 1af9b6b..b489797 100644 --- a/content/docs/pb-cli/promql.mdx +++ b/content/docs/pb-cli/promql.mdx @@ -11,13 +11,22 @@ Parseable can store metrics data ingested via OpenTelemetry or Prometheus remote pb query promql run "" --dataset --from ``` -```bash -# Range query: rate of HTTP requests over the last hour, 1-minute resolution -pb query promql run "rate(http_requests_total[5m])" --dataset otel_metrics --from 1h --step 1m + + -# Instant query: current value only -pb query promql run "up" --dataset otel_metrics --instant -``` + ```bash + pb query promql run "rate(http_requests_total[5m])" --dataset otel_metrics --from 1h --step 1m + ``` + + + + + ```bash + pb query promql run "up" --dataset otel_metrics --instant + ``` + + + ### Flags @@ -41,14 +50,21 @@ The TUI has panels for Dataset, Query expression, Time Range, Step size, and Res ## Explore labels and series +List all label names in a metrics dataset: + ```bash -# List all label names in a metrics dataset pb query promql labels --dataset otel_metrics +``` + +List all values for a specific label: -# List all values for a specific label +```bash pb query promql label-values job --dataset otel_metrics +``` -# Find series matching a selector +Find series matching a selector: + +```bash pb query promql series --match 'http_requests_total' --dataset otel_metrics pb query promql series --match '{job="api-server"}' --dataset otel_metrics ``` @@ -57,14 +73,21 @@ pb query promql series --match '{job="api-server"}' --dataset otel_metrics High cardinality labels are a common cause of performance issues. These commands help you find them. +Labels with the most distinct values: + ```bash -# Labels with the most distinct values pb query promql cardinality label-names --dataset otel_metrics --limit 20 +``` + +Series count per value for a specific label: -# Series count per value for a specific label +```bash pb query promql cardinality label-values --label job --dataset otel_metrics +``` -# Currently active series +Currently active series: + +```bash pb query promql cardinality active-series --dataset otel_metrics --selector '{job="api"}' ``` @@ -82,4 +105,4 @@ Shows storage statistics for the metrics dataset, broken down by the top N serie pb query promql active-queries ``` -Lists any PromQL queries currently running on the server. Useful for debugging slow or stuck queries. +Lists any PromQL queries currently running on the server. Useful for debugging slow or stuck queries. \ No newline at end of file diff --git a/content/docs/pb-cli/query.mdx b/content/docs/pb-cli/query.mdx index 944d388..92ed7bc 100644 --- a/content/docs/pb-cli/query.mdx +++ b/content/docs/pb-cli/query.mdx @@ -21,24 +21,42 @@ pb query run "SELECT * FROM backend" --from 10m --to now | Absolute | `2024-01-15T00:00:00Z` | Exact RFC3339 timestamp | | Keyword | `now` | Current time | +Last 30 minutes: + ```bash -# Last 30 minutes pb query run "SELECT * FROM logs LIMIT 100" --from 30m +``` + +Specific time window: -# Specific time window +```bash pb query run "SELECT count(*) FROM logs" --from 2024-01-01T00:00:00Z --to 2024-01-02T00:00:00Z +``` + +Default (last 1 minute if `--from` is not specified): -# Default: last 1 minute +```bash pb query run "SELECT * FROM logs" ``` -## JSON output +## Output format -Use `--output json` to get structured output suitable for scripting: + + -```bash -pb query run "SELECT * FROM logs LIMIT 50" --from 1h --output json -``` + ```bash + pb query run "SELECT * FROM logs LIMIT 50" --from 1h + ``` + + + + + ```bash + pb query run "SELECT * FROM logs LIMIT 50" --from 1h --output json + ``` + + + ## Save and reuse queries @@ -79,4 +97,4 @@ The TUI has three panels - Query, Time Range, and Results Table. Navigate betwee Field names containing dots (OTel convention, e.g. `service.name`) or hyphens are automatically quoted in queries. You don't need to add quotes manually. - + \ No newline at end of file diff --git a/mdx-components.tsx b/mdx-components.tsx index f3d395f..2163b9d 100644 --- a/mdx-components.tsx +++ b/mdx-components.tsx @@ -2,6 +2,7 @@ import { ImageZoom } from 'fumadocs-ui/components/image-zoom'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; +import { Tabs, Tab } from 'fumadocs-ui/components/tabs'; import { createAPIPage } from 'fumadocs-openapi/ui'; import { openapi } from './lib/source'; import type { MDXComponents } from 'mdx/types'; @@ -23,6 +24,8 @@ export function getMDXComponents(components: MDXComponents = {}): MDXComponents Callout, Card, Cards, + Tabs, + Tab, ProBadge, EnterpriseBadge, OfferingPills,