docs: update pb cloud and agent guidance

content/docs/pb-cli/admin.mdx

@@ -23,10 +23,12 @@ This starts an interactive prompt where you choose a privilege level and the dat
 
 | 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

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. A human should configure and verify the intended profile before giving the agent control.
+
+```bash
+pb login
+pb status --output json
+```
+
+The agent uses the saved profile automatically. 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. Profile names are user-defined and do not need to be named `agent`.
+
+<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 multiple profiles exist, the human should select the intended profile before starting the agent:
+
+```bash
+pb profile default automation-readonly --output json
+pb status --output json
+```
+
+## Prefer read operations and JSON
+
+Agents should use structured output when supported:
+
+```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>
+
+Do not place API keys in prompts, source control, logs, or agent instruction files.

content/docs/pb-cli/aliases.mdx

@@ -37,7 +37,7 @@ 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 |
 

content/docs/pb-cli/connect.mdx

@@ -7,17 +7,13 @@ description: "Create a profile and authenticate with your Parseable instance."
 
 ## 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 wizard. Choose self-hosted Parseable or Parseable Cloud, then select the available authentication method.
 
 ```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 authenticate with a username and password or an API key. For Parseable Cloud, authenticate in the browser or enter a Parseable Cloud API key. The selected Cloud workspace is saved in the profile.
 
 Once complete, the profile is saved and set as the active default.
 
@@ -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

content/docs/pb-cli/index.mdx

@@ -3,7 +3,7 @@ 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 developers and operators a fast terminal workflow for SQL log queries, PromQL metrics exploration, live event tailing, saved investigations, profiles, datasets, 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.
 
@@ -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 |
@@ -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

content/docs/pb-cli/install.mdx

@@ -69,16 +69,6 @@ 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`:

content/docs/pb-cli/meta.json

@@ -13,6 +13,7 @@
     "tail",
     "datasets",
     "admin",
-    "aliases"
+    "aliases",
+    "agents"
   ]
 }

content/docs/pb-cli/tail.mdx

@@ -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` connected to the server successfully over HTTP, but could not reach the server-advertised gRPC port. `8001` is the default, but deployments can configure another 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. For a default Docker setup, expose it with `-p 8001:8001`. For a custom deployment, expose the value configured by the server and allow outbound TCP access to that port.