parseablehq · nitisht · Jul 28, 2026 · Jul 20, 2026 · Jul 27, 2026
diff --git a/.source/browser.ts b/.source/browser.ts
diff --git a/.source/server.ts b/.source/server.ts
diff --git a/content/docs/pb-cli/admin.mdx b/content/docs/pb-cli/admin.mdx
@@ -7,7 +7,7 @@ description: "Manage users and role-based access control with pb user and pb rol
 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.
+Parseable uses role-based access control. In practice, that means you define roles first, then assign those roles to users.
 
 ## Roles
 
@@ -17,16 +17,18 @@ Parseable uses role-based access control (RBAC). Roles define what a user can do
 pb role add <name>
 ```
 
-This starts an interactive prompt where you choose a privilege level and the dataset it applies to.
+This opens an interactive prompt where you choose the privilege level and the dataset scope.
 
 **Privilege levels:**
 
 | Privilege | Access |
 |---|---|
+| `none` | No server privileges |
+| `admin` | Full system-wide access |
+| `editor` | Read and write access across datasets |
 | `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
@@ -66,7 +68,7 @@ pb role rm <name>
 pb user add <username>
 ```
 
-The server generates a password and prints it. Save it because it cannot be retrieved later.
+The server generates a password and prints it once. Keep it somewhere safe because it cannot be retrieved later.
 
 Assign roles at creation time:
 

diff --git a/content/docs/pb-cli/agents.mdx b/content/docs/pb-cli/agents.mdx
@@ -0,0 +1,61 @@
+---
+title: "AI Agent Access"
+description: "Use pb safely from AI coding agents and automation tools."
+---
+
+AI coding agents can use the installed `pb` binary through shell commands. The safest setup is to have a human create and verify the profile first, then let the agent use that saved connection.
+
+```bash
+pb login
+pb status --output json
+```
+
+Once the profile is ready, the agent can use it directly. It does not need the API key in its prompt and should not read `~/.config/pb/config.toml`.
+
+## Non-interactive profile setup
+
+For automation, load the API key from a secret store or environment variable. The profile name is up to you.
+
+<Tabs items={['Self-hosted', 'Parseable Cloud']}>
+  <Tab value="Self-hosted">
+
+  ```bash
+  pb profile add automation-readonly https://parseable.example.com \
+    --api-key "$PARSEABLE_API_KEY" --output json
+  ```
+
+  </Tab>
+  <Tab value="Parseable Cloud">
+
+  ```bash
+  pb cloud profile add --name automation-readonly \
+    --api-key "$PARSEABLE_CLOUD_API_KEY" --output json
+  ```
+
+  </Tab>
+</Tabs>
+
+If more than one profile exists, select the intended one before starting the agent:
+
+```bash
+pb profile default automation-readonly --output json
+pb status --output json
+```
+
+## Prefer read operations and JSON
+
+When an agent needs to read results programmatically, prefer JSON output:
+
+```bash
+pb status --output json
+pb dataset list --output json
+pb dataset info <dataset> --output json
+pb sql run "SELECT * FROM <dataset> LIMIT 10" --output json
+pb promql run "up" --dataset <metrics-dataset> --instant --output json
+```
+
+<Callout type="warn">
+Create a dedicated read-only API key or role with only the query and metadata permissions the agent needs. Never give an agent an administrator key or a shared human credential. Read-only access must be enforced by Parseable on the server; CLI instructions alone cannot prevent create, update, or delete attempts.
+</Callout>
+
+Keep API keys out of prompts, source control, logs, and agent instruction files.
diff --git a/content/docs/pb-cli/aliases.mdx b/content/docs/pb-cli/aliases.mdx
@@ -3,7 +3,7 @@ title: "Aliases and Reference"
 description: "Short command aliases and the current pb command surface."
 ---
 
-`pb` includes Linux-style aliases for common commands, so they are easy to remember if you already use shell commands like `ls`, `rm`, `stat`, and `ps`. Use the long form in scripts when readability matters, and the short form for day-to-day terminal work.
+`pb` includes Linux-style aliases for common commands. If you already use commands like `ls`, `rm`, `stat`, and `ps` in the shell, the short forms will feel familiar. The long form is still the better choice in scripts when readability matters more.
 
 | Linux-style alias | Meaning in `pb` |
 |---|---|
@@ -37,13 +37,13 @@ description: "Short command aliases and the current pb command surface."
 | Query metrics | `pb promql` | Run PromQL, inspect labels and series, analyze cardinality, view TSDB stats |
 | Stream events | `pb tail` | Watch new events from a dataset |
 | Datasets | `pb dataset` | List, inspect, create, and remove datasets |
-| Profiles | `pb login`, `pb profile`, `pb logout` | Manage Parseable server connections |
+| Profiles | `pb login`, `pb cloud profile`, `pb profile`, `pb logout` | Manage self-hosted and Parseable Cloud connections |
 | Access control | `pb user`, `pb role` | Manage users and roles |
 | System | `pb status`, `pb version` | Check connectivity and print CLI version details |
 
 ## Help
 
-Use built-in help to inspect flags and examples for any command:
+Use built-in help whenever you want to inspect flags and examples for a command:
 
 ```bash
 pb --help

diff --git a/content/docs/pb-cli/connect.mdx b/content/docs/pb-cli/connect.mdx
@@ -3,27 +3,23 @@ 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.
+`pb` stores server connections as named **profiles**. Each profile keeps the server URL and authentication details for one Parseable instance. If you work with more than one environment, such as staging and production, profiles let you switch between them without re-entering credentials each time.
 
 ## Interactive login (recommended)
 
-Run `pb login` to start the interactive wizard. It walks you through the server URL, authentication method, credentials, and profile name.
+Run `pb login` to start the interactive setup. Choose self-hosted Parseable or Parseable Cloud, then pick the authentication method that fits that server.
 
 ```bash
 pb login
 ```
 
-The wizard prompts you for:
-- Server URL (e.g. `https://logs.mycompany.com`)
-- Auth method - username/password or API key
-- Credentials
-- Profile name (defaults to `default`)
+For self-hosted Parseable, enter the server URL and sign in with either a username and password or an API key. For Parseable Cloud, sign in in the browser or provide a Parseable Cloud API key. The selected Cloud workspace is then saved into the profile.
 
-Once complete, the profile is saved and set as the active default.
+When the flow finishes, that profile becomes the active default.
 
 ## Non-interactive login
 
-For scripts and CI pipelines, use `pb profile add` to create a profile without prompts:
+For scripts and CI pipelines, use `pb profile add` when you want to create a profile without prompts:
 
 ```bash
 pb profile add <name> <url> <username> <password>
@@ -33,6 +29,18 @@ pb profile add <name> <url> <username> <password>
 pb profile add production https://logs.mycompany.com admin s3cr3t
 ```
 
+Use a self-hosted API key instead of username and password:
+
+```bash
+pb profile add production-key https://logs.mycompany.com --api-key psk_xxx
+```
+
+Add a Parseable Cloud API-key profile:
+
+```bash
+pb cloud profile add --name production-cloud --api-key psk_xxx
+```
+
 You can also omit credentials and let `pb` prompt for them:
 
 ```bash
@@ -41,14 +49,14 @@ pb profile add production https://logs.mycompany.com
 
 ## Managing profiles
 
-List and switch profiles:
+Once you have more than one profile, these are the commands you will use most often:
 
 ```bash
 pb profile list
 pb profile default staging
 ```
 
-Update or remove a profile:
+To update or remove a saved profile:
 
 ```bash
 pb profile update production https://new-url.mycompany.com
@@ -63,7 +71,7 @@ pb profile rm old-staging
 pb status
 ```
 
-This validates that the active profile can reach the server and shows server details when available:
+This checks whether the active profile can reach the server and shows basic server details when they are available:
 
 ```
 Profile : production
@@ -78,9 +86,9 @@ Status  : Connected  (server v1.4.2)
 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`.
+`pb logout` removes the active profile from the local config. If you want to log out of a different profile, switch to it first with `pb profile default <name>`, then run `pb logout`.
 
-If you want to remove the saved profile completely, delete it instead:
+If you want to remove a specific saved profile directly, use:
 
 ```bash
 pb profile remove <name>
@@ -97,5 +105,5 @@ Profiles are stored in a TOML config file on disk:
 | 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.
+All commands use the active default profile automatically. Use `pb profile default <name>` whenever you want to change which server `pb` talks to by default.
 </Callout>
diff --git a/content/docs/pb-cli/index.mdx b/content/docs/pb-cli/index.mdx
@@ -3,9 +3,9 @@ title: pb CLI
 description: Query logs, explore metrics, tail live events, and manage Parseable from your terminal.
 ---
 
-`pb` is the official command line interface for Parseable. It gives developers and operators a fast terminal workflow for SQL log queries, PromQL metrics exploration, live event tailing, saved investigations, profiles, datasets, users, and roles.
+`pb` is the official command line interface for self-hosted Parseable and Parseable Cloud. It gives you a terminal-first way to connect to a server, run SQL and PromQL queries, tail live events, manage datasets, and work with users and roles.
 
-Use it as a regular CLI in scripts and CI, or open the full-screen interactive TUIs when you want a table-driven way to explore logs or metrics without leaving your shell.
+You can use it in scripts and CI, or open the interactive terminal views when you want to explore logs and metrics without switching to the browser.
 
 ## Quick start
 
@@ -34,6 +34,7 @@ pb tail backend
 | Command | Description |
 |---|---|
 | `pb login` | Start an interactive wizard to connect to a Parseable server and save the connection as a profile |
+| `pb cloud profile` | Add a Parseable Cloud profile with a Cloud API key |
 | `pb profile` | Add, list, switch, update, and remove saved server profiles |
 | `pb status` | Verify the active connection and display server version information |
 | `pb sql` | Run SQL queries, save SQL queries, and open the interactive SQL table view |
@@ -65,11 +66,11 @@ SQL and PromQL both support an interactive full-screen TUI with `-i`. In this mo
   </Tab>
 </Tabs>
 
-Navigate between panels with `Tab` and `Shift+Tab`. Press `Ctrl+R` to run the query. Results open in a scrollable table with row navigation, column navigation, and filtering.
+Navigate between panels with `Tab` and `Shift+Tab`. Press `Ctrl+R` to run the query. Results open in a scrollable table where you can move through rows, inspect columns, and filter what you see.
 
 ## Output modes
 
-Commands that return structured data support `--output json` for automation. SQL queries without `-i` print plain terminal output; add `-i` to open the interactive table view.
+Commands that return structured data support `--output json`, which makes them easier to use in scripts and automation. SQL queries without `-i` print directly in the terminal. Add `-i` when you want the interactive table view instead.
 
 ```bash
 pb dataset list
@@ -82,8 +83,9 @@ pb promql run "up" --dataset otel_metrics --instant --output json
 
 ## Getting started
 
-1. [Install pb](/docs/pb-cli/install) - install with the script, Homebrew, Go, or a release archive
+1. [Install pb](/docs/pb-cli/install) - install with the script, Homebrew, or a release archive
 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 logs with `pb sql`
 4. [Run a PromQL query](/docs/pb-cli/promql) - query metrics with `pb promql`
 5. [Use aliases](/docs/pb-cli/aliases) - learn the short command forms such as `ls`, `rm`, `stat`, and `set-url`
+6. [Use pb with AI agents](/docs/pb-cli/agents) - configure safe, read-only agent access
diff --git a/content/docs/pb-cli/install.mdx b/content/docs/pb-cli/install.mdx
@@ -44,7 +44,7 @@ Use the full tap name. `brew install pb` installs an unrelated Homebrew cask.
 
 ## Release archive
 
-Download the latest archive for your operating system and architecture from the [GitHub releases page](https://github.com/parseablehq/pb/releases/latest), extract it, and move the binary to a directory in your `PATH`.
+If you prefer to install manually, download the latest archive for your operating system and architecture from the [GitHub releases page](https://github.com/parseablehq/pb/releases/latest), extract it, and move the binary to a directory in your `PATH`.
 
 ```bash
 tar xzf pb_*.tar.gz
@@ -69,19 +69,9 @@ On macOS, a manually downloaded binary may be blocked on first run. Allow it onc
 xattr -d com.apple.quarantine /usr/local/bin/pb
 ```
 
-## Using Go
-
-If you have Go installed, you can build and install `pb` from source:
-
-```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, confirm that `pb` is on your `PATH`:
+After installation, confirm that `pb` is available on your `PATH`:
 
 ```bash
 pb --help

diff --git a/content/docs/pb-cli/meta.json b/content/docs/pb-cli/meta.json
@@ -13,6 +13,7 @@
     "tail",
     "datasets",
     "admin",
-    "aliases"
+    "aliases",
+    "agents"
   ]
 }
diff --git a/content/docs/pb-cli/tail.mdx b/content/docs/pb-cli/tail.mdx
@@ -3,7 +3,7 @@ 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.
+`pb tail` connects to a dataset and streams new events as they arrive. It is useful when you want to watch a service in real time, confirm that ingestion is working, or keep an eye on a pipeline while it is running.
 
 ## Usage
 
@@ -16,7 +16,7 @@ pb tail <dataset-name>
 pb tail backend
 ```
 
-Events are printed as newline-delimited JSON, one event per line. Press `Ctrl+C` to stop.
+Events are printed as newline-delimited JSON, one event per line. Press `Ctrl+C` when you want to stop the stream.
 
 ```
 ● watching backend... (ctrl+c to stop)
@@ -26,7 +26,7 @@ Events are printed as newline-delimited JSON, one event per line. Press `Ctrl+C`
 
 ## Piping to jq
 
-Because output is newline-delimited JSON, you can pipe directly to `jq` for filtering and formatting:
+Because the output is newline-delimited JSON, you can pipe it straight into `jq` for filtering and formatting:
 
 ```bash
 # Pretty-print all events
@@ -51,22 +51,22 @@ 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:
+`pb tail` uses Apache Arrow Flight over gRPC for streaming. It first reads the gRPC port advertised by the connected Parseable server, then opens the streaming connection on that port. The default self-hosted ports are:
 
 | Port | Protocol | Purpose |
 |---|---|---|
 | `8000` | HTTP | Main Parseable API (login, query, datasets) |
-| `8001` | gRPC | Arrow Flight streaming (used by `pb tail`) |
+| `8001` | gRPC | Default streaming port used by `pb tail` |
 
 ## Troubleshooting
 
 **Error: `rpc error: code = Unavailable ... dial tcp <ip>: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`.
+This means `pb tail` reached the server over HTTP, but could not reach the gRPC port advertised by that server. `8001` is the default, but a deployment can expose a different value.
 
 Possible causes:
-- Port `8001` is blocked by a firewall on the server
-- Port `8001` is not exposed in your Docker or Kubernetes setup
+- The advertised gRPC port is blocked by a firewall on the server
+- The advertised gRPC port 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`.
+To fix it, make sure the configured gRPC port is open and reachable from your machine. In a default Docker setup, expose it with `-p 8001:8001`. In a custom deployment, expose the port configured by the server and allow outbound TCP access to it.