@grepr/cli 1.11.3-44a8959 → 1.11.3-9ab9226

package/build/dist/docs-index/1cf764b8-5274-48ba-9f2c-7ca9633669eb.txt

@@ -0,0 +1,142 @@
+Connect Claude or Claude Code to the Grepr MCP server with OAuth sign-in, or connect any MCP client with a service account access token.
+
+# Connect to the Grepr MCP server
+
+Grepr provides a remote Model Context Protocol server, or MCP server, that lets AI assistants work with your Grepr organization. The server provides tools to list pipelines, browse datasets and templates, query logs, validate SQL and Grok rules, and propose pipeline changes. Every tool call is authorized with the same role-based permissions as the Grepr UI and REST APIs.
+
+The MCP server is available at the following endpoints:
+
+| Region | Endpoint |
+| --- | --- |
+| US | `https://app.grepr.ai/mcp` |
+| EU | `https://app.euc1.grepr.ai/mcp` |
+
+The examples on this page use the US endpoint. If your organization is in the EU region, replace the endpoint and use the EU client ID.
+
+You can authenticate in two ways:
+
+* OAuth sign-in: You sign in interactively with your Grepr user account. Use this for Claude and Claude Code.
+* Service account credentials: Your client authenticates as a Grepr service account. Use this for Claude Tag in Slack, for automation, and for MCP clients that do not support the OAuth sign-in flow.
+
+## Sign in with OAuth
+
+Grepr registers a dedicated OAuth client for each supported MCP client. To connect, configure your MCP client with the Grepr endpoint and the matching client ID from the following table, then sign in with your Grepr user account. When the sign-in page prompts for an organization, enter your Grepr organization name.
+
+| MCP client | US client ID | EU client ID |
+| --- | --- | --- |
+| Claude | `us3sBOgZj6hERktG9yZEVwujaJe3j9L0` | `HOnxCPNGnzdGlfXBM2sff0twoolRnDj9` |
+| Claude Code | `jlCTdLYzDkkTSc2I7MdI0SBw48AOdJM6` | `GlEIcfSbge5gqN4o918fLXKVONP2twBh` |
+
+### Claude
+
+These steps apply to Claude on the web, the Claude desktop apps, and the Claude mobile apps.
+
+1. In Claude, go to **Settings** > **Connectors** and click **Add custom connector**.
+2. Enter `https://app.grepr.ai/mcp` as the URL.
+3. Under **Advanced settings**, enter `us3sBOgZj6hERktG9yZEVwujaJe3j9L0` as the **OAuth Client ID**. Leave the client secret empty.
+4. Complete the sign-in flow with your Grepr user account.
+
+### Claude Code
+
+Add the server with the Grepr client ID and the fixed callback port:
+
+```bash
+claude mcp add --transport http --client-id jlCTdLYzDkkTSc2I7MdI0SBw48AOdJM6 --callback-port 6280 grepr https://app.grepr.ai/mcp
+```
+
+The `--callback-port 6280` flag is required. Without it, Claude Code picks a random port and the sign-in fails with a callback URL mismatch.
+
+Then open Claude Code, run `/mcp`, select `grepr`, and complete the sign-in flow in your browser with your Grepr user account.
+
+## Connect Claude Tag in Slack
+
+Claude Tag is Claude in Slack channels. In a channel, Claude acts as a shared identity that an Owner of your Claude organization configures, not as the person who sends the message. Everyone in a channel that the configuration covers gets the same Grepr access, so connect a dedicated Grepr service account with the narrowest role that fits the channel. Direct messages with Claude in Slack run on your own Claude account and use the Claude connector described earlier on this page.
+
+Before you start, you need:
+
+* The Owner role in your Claude organization. Claude Tag is available on the Claude Team and Enterprise plans.
+* A Grepr service account and its client ID and client secret. See [Manage Grepr service accounts](/admin/service-accounts).
+* The Grepr plugin for Claude Tag: [grepr-claude-tag-plugin.zip](/plugins/grepr-claude-tag-plugin.zip). Claude Tag reaches an MCP server only through a plugin. The plugin contains two files: a manifest, and an `.mcp.json` file that names the US and EU Grepr MCP endpoints.
+
+### Upload the plugin
+
+1. In Claude, go to **Admin settings** > **Plugins** and click **Add plugins**.
+2. Select **Upload a file** and upload `grepr-claude-tag-plugin.zip`.
+
+The plugin is now in your organization's catalog. It does nothing until you turn it on in an access bundle.
+
+### Turn on the plugin and add the credential
+
+An access bundle is the set of credentials and plugins that Claude uses in the channels the bundle covers. The **Default Slack** scope covers every channel in your Slack workspace. To limit Grepr access to one channel, select that channel's scope instead.
+
+1. Go to **Admin settings** > **Claude Tag** and, under **Claude Tag's access**, select the **Slack** tab.
+
+2. Select the **Default Slack** scope, or the channel to connect.
+
+3. Next to **Access bundles**, click the **+** button and select **Create new bundle**, or open the existing bundle.
+
+4. On the **Plugins** tab, turn on **grepr-mcp**.
+
+5. On the **Credentials** tab, click **Connect** next to **Custom tool** and enter the following values:
+
+   \| Field | Value | | --- | --- | | Name | `Grepr` | | Credential type | **OAuth 2.0 client credentials** | | Token URL | `https://auth.grepr.ai/oauth/token`, or `https://auth.eu.grepr.ai/oauth/token` for the EU region | | Client ID | The service account client ID | | Client secret | The service account client secret | | Audience | `service` | | Allowed websites | `app.grepr.ai`, or `app.euc1.grepr.ai` for the EU region |
+
+6. Save the connection and confirm that its status is **Active** on the **Access bundles** page.
+
+> A bundle on a public channel gives its access to anyone who joins the channel. Keep a service account with edit permissions in a bundle on a private channel.
+
+### Test the connection
+
+In a channel the bundle covers, start a new thread and send:
+
+```text
+@Claude list the Grepr pipelines
+```
+
+Threads that started before you turned on the plugin do not pick it up. If Claude reports that a host was blocked by the network egress proxy, add the host it names to the **Allowed websites** of the Grepr connection.
+
+## Authenticate with a service account token
+
+For automation, and for MCP clients that are not in the table and do not support OAuth 2.0 client credentials, authenticate with a service account access token. The MCP endpoint accepts the same access tokens as the Grepr REST APIs.
+
+1. Create a service account. See [Manage Grepr service accounts](/admin/service-accounts).
+
+2. Obtain an access token. See [Authenticate to Grepr REST APIs](/apis/authentication).
+
+3. Configure your MCP client to send the token in the `Authorization` header. Most clients accept a headers object in their MCP server configuration:
+
+   ```json
+   {
+     "headers": {
+       "Authorization": "Bearer <access-token>"
+     }
+   }
+   ```
+
+> The access token expires after 24 hours and has no refresh token, so your client cannot renew it automatically. When the token expires, obtain a new token and update your client configuration. For scheduled automation, obtain a new token at the start of each run.
+
+## Frequently Asked Questions
+
+### What is the Grepr MCP server URL?
+
+The MCP endpoint is https\://app.grepr.ai/mcp for the US region and https\://app.euc1.grepr.ai/mcp for the EU region.
+
+### How do I connect Claude to Grepr?
+
+Add a custom connector in Claude with the URL https\://app.grepr.ai/mcp, and enter the Grepr client ID for Claude under Advanced settings. Then sign in with your Grepr user account.
+
+### Why does the MCP sign-in fail with a callback URL mismatch?
+
+Grepr registers exact OAuth callback URLs. Clients that open the sign-in flow on a local port must use port 6280, for example with the --callback-port 6280 flag in Claude Code.
+
+### Can I use the Grepr MCP server without OAuth?
+
+Yes. The MCP endpoint accepts the same service account access tokens as the Grepr REST APIs. Send the token in the Authorization header as a Bearer token.
+
+### Can I use Grepr from Claude in Slack?
+
+Yes. Upload the Grepr plugin for Claude Tag, turn it on in an access bundle, and add an OAuth 2.0 client credentials connection for app.grepr.ai with a Grepr service account, the token URL https\://auth.grepr.ai/oauth/token, and the audience service.
+
+### Which organization does an MCP session use?
+
+The organization you enter at sign-in, or the organization of the service account that issued the token. The MCP session is scoped to that organization.

package/build/dist/docs-index/662627ef-2625-4da4-8201-829628412942.txt

@@ -0,0 +1,11 @@
+# AnalyticsDiagnosticFix
+
+A change that resolves this diagnostic, when the server has verified one: today, the GROUP BY entry that makes an ungrouped SELECT expression valid.
+
+**Type**: `object`
+
+## Properties
+
+- name: addGroupBy (required)
+  type: string
+  description: A GROUP BY entry to append: the result column's alias, quoted when it starts with a digit, or its expression when it has no alias. The server has translated the query with this entry added and found it valid.

package/build/dist/docs-index/{eaf23c03-0821-4d6e-a76b-b30d5f8086fc.txt → 7a5079ef-a051-4b3a-ad6c-9921749a5dac.txt}

@@ -6,6 +6,9 @@ Request constraints, followed by the first SQL failure when the request is compl
 
 ## Properties
 
+- name: fix (optional)
+  type: `AnalyticsDiagnosticFix`
+
 - name: message (required)
   type: string
   description: What is wrong, as a finished sentence to show the person editing the query.

package/build/dist/docs-index/{c3d4b23d-f12e-477c-9d40-f4a7158b2e3a.txt → b039f5e9-b71b-4c46-9172-96ad15f53a8b.txt}

@@ -10,14 +10,16 @@ Log Explorer's Analyze mode groups and aggregates the logs your search returns i
 2. Enter a search query to filter the logs you want to analyze. Analyze mode accepts the same [Datadog-like syntax](/queries/datadog) and [New Relic log query-like syntax](/queries/new-relic) as searching.
 3. Open the **Analyze...** drawer under the search controls.
 4. Under **SELECT**, enter one expression per result column, and name it in the **Alias** field beside it. An alias is optional; a column you leave unnamed is named for you, after the field or function it computes.
-5. Under **GROUP BY**, add the expressions whose distinct combinations you want as rows. When you finish a new grouping expression, the builder adds a SELECT row for it and groups by that row's alias, so the expression is written once. Renaming the alias renames the grouping with it, and removing the column puts the expression back under GROUP BY. A GROUP BY row can name any SELECT alias. Without a grouping expression, an analysis made only of aggregates returns a single row.
+5. Under **GROUP BY**, add the expressions whose distinct combinations you want as rows. Each grouping expression also becomes a result column, so the rows show the values they are grouped on. Without a grouping expression, an analysis made only of aggregates returns a single row.
 6. Under **HAVING**, enter a condition over the aggregates to keep only some of the groups. Leave it empty to keep every group.
 7. Under **ORDER BY**, add the expressions to sort by and pick ascending or descending for each one.
-8. Set **Row limit**, the maximum number of rows to return. An analysis returns 2,500 rows by default. The field stops at the largest limit your deployment allows, and a larger one is refused with a message naming that maximum.
+8. Set **Row limit**, the maximum number of rows to return. An analysis returns 2,500 rows by default, up to the largest limit your deployment allows.
 9. Set **Scan budget** to cap how much of the lake the query may read, then run the analysis.
 
 The drawer's clauses are the SQL ones, so an analysis reads the way the query does: SELECT computes, GROUP BY collapses, HAVING filters the groups, ORDER BY and the row limit choose which of them you see. GROUP BY, HAVING and ORDER BY can refer to a result by its alias.
 
+Every SELECT column is either an aggregate or one of the grouping expressions. To count events by a field, add the field under SELECT and group by it.
+
 ## Log fields
 
 Expressions address the stored log columns by the following names:
@@ -34,7 +36,7 @@ Expressions address the stored log columns by the following names:
 
 > These are the Grepr SQL column names, which use `snake_case`. They are not the camelCase field names of the log event JSON that the search and export APIs return.
 
-A tag holds an array of values, so the suggestion for a tag key groups by the sorted, comma-joined set of its values — two events tagged with the same values in a different order land in one group. The suggestion shows this expression beside the key, so you can see what picking the key inserts:
+A tag holds an array of values, so picking a tag key from the suggestions groups by the sorted, comma-joined set of its values — two events tagged with the same values in a different order land in one group:
 
 ```sql
 ARRAY_TO_STRING(SORT_ARRAY(tags['service']), ',')
@@ -72,13 +74,13 @@ MIN(CAST(@duration_ms AS DOUBLE))
 
 > Sorting by an attribute you have not cast sorts it as text, so `100` sorts before `99`. Cast it to sort numerically.
 
-A path segment is a name or a number, and the segments are separated by dots. An `@` with nothing after it, or a segment that starts with a digit, is a syntax error, and Log Explorer reports it against the expression you typed.
+A path segment is a name or a number, and the segments are separated by dots.
 
 ## Expressions
 
 Expressions are Grepr SQL, so aggregates, `CASE`, `CAST` and scalar functions are all available.
 
-Every function an analysis can call is listed in the [Analyze function reference](/queries/analyze/functions), with its arguments and a worked example. Focus an expression box or start typing to find fields, functions, sampled tag and attribute keys, and result aliases. Suggestions match the text you type; they do not check whether each option fits the surrounding SQL. Typing a space closes the menu. Press the Down arrow key to open it again.
+Every function an analysis can call is listed in the [Analyze function reference](/queries/analyze/functions), with its arguments and a worked example. Focus an expression box or start typing to find fields, functions, sampled tag and attribute keys, and result aliases.
 
 > The [SQL transform function reference](/transforms/sql-transform/sql-functions) does **not** describe Analyze. A SQL transform runs inside a pipeline on Flink SQL; an analysis runs on the query engine over the data lake. The two support different functions, so a function listed there may not exist here, and the autocomplete offers functions that page does not list.
 
@@ -95,7 +97,7 @@ APPROX_PERCENTILE(@duration_ms, 0.95)
 CASE WHEN severity >= 4 THEN 'error' ELSE 'ok' END
 ```
 
-`SEVERITY_TEXT` names the OpenTelemetry severity bucket a severity number falls in: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` or `FATAL`, and nothing for a log with no severity. It takes a whole number, so text and fractional operands are errors rather than values Grepr will quietly convert. Grouping by it is the usual way to count logs per level:
+`SEVERITY_TEXT` names the OpenTelemetry severity bucket a severity number falls in: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` or `FATAL`, and nothing for a log with no severity. It takes a whole number, so cast an attribute before passing it. Grouping by it is the usual way to count logs per level:
 
 ```sql
 -- Under SELECT
@@ -107,7 +109,7 @@ SEVERITY_TEXT(severity)
 
 ## Name the results
 
-Every SELECT column takes an optional alias, entered in the **Alias** field beside the expression. The alias becomes the result column's name. Pick a tag from the suggestions and the alias is filled in with the tag's own key, since the expression that reads a tag is a call wrapped around it. Leave the alias empty and Grepr names the column after the expression itself:
+Every SELECT column takes an optional alias, entered in the **Alias** field beside the expression. The alias becomes the result column's name. Leave it empty and Grepr names the column after the expression itself:
 
 | Expression | Alias | Result column |
 | --- | --- | --- |
@@ -129,9 +131,9 @@ p95 / 1000
 
 Aliases are lowercase, made of letters, digits and underscores, up to 128 characters, and a reference has to match exactly.
 
-> The alias goes in its own field, not in the expression: writing `AS p95` inside an expression is rejected. An alias is available to GROUP BY, HAVING and ORDER BY, and to the SELECT columns after the one that defines it.
+> Enter the alias in its own field, not in the expression: `AS p95` inside an expression is not valid. An alias is available to GROUP BY, HAVING and ORDER BY, and to the SELECT columns after the one that defines it.
 
-Reserved SQL words cannot be aliases, because the query engine would read them as syntax. Log Explorer refuses one and suggests an alternative, which is why the default first column is `count0` rather than `count`. The same rule applies to an alias Grepr derives for you: a derived name that lands on a reserved word gains a `0`.
+Reserved SQL words cannot be aliases, because the query engine would read them as syntax. That is why the default first column is `count0` rather than `count`, and why a name Grepr derives for you gains a `0` when it lands on a reserved word.
 
 > `count`, `max`, `min`, `sum`, `value`, `date` and `year` are reserved. Ordinary field names such as `level`, `name`, `type`, `path`, `service`, `host` and `user` are not.
 
@@ -148,8 +150,6 @@ Each duration is a whole number of milliseconds, seconds, minutes, hours, or day
 
 Windows are aligned to the clock rather than to the start of your time range, so the first and last windows of a range can be partial.
 
-Setting a window puts `window_start` and `window_end` first among the result columns and sorts the analysis by `window_start` descending, so the newest window leads without any further setup. Both are yours to change: drag the columns elsewhere, or edit the sort. Removing the window removes the bound columns and drops the sorts that referred to them.
-
 In the API, the window is the `window` object of the structured analytics query, with ISO-8601 durations:
 
 ```json
@@ -160,7 +160,7 @@ In the API, the window is the `window` object of the structured analytics query,
 
 Click a column header to sort the rows you already have. No second run happens and no scan budget is spent; Shift-click adds a second sort instead of replacing the first.
 
-When an analysis comes back at its row limit, the rows you have are only the top of the ranking, so sorting them on the page can put the wrong rows first. The table says so and offers **Sort on the server**, which puts the sort into ORDER BY and runs the analysis again so the engine ranks every matching row.
+When an analysis comes back at its row limit, the rows you have are only the top of the ranking, so sorting them on the page can put the wrong rows first. **Sort on the server** puts the sort into ORDER BY and runs the analysis again, so the engine ranks every matching row.
 
 ## Share an analysis
 
@@ -168,8 +168,6 @@ The whole analysis lives in the page URL, so copying the link from the address b
 
 Opening such a link seats every control and runs the analysis once, so the recipient sees the rows rather than a filled-in form waiting for a click. Back and Forward move between analyses you have already run, restoring the controls without re-running and spending scan budget again.
 
-An analysis long enough to overflow the address bar cannot be carried, and Log Explorer says so rather than sharing a link that silently restores something different.
-
 ## Result values
 
 Each result row is a JSON object keyed by column name, so a column holds whatever the underlying attribute held, such as a number, a string, a boolean, or a nested object. Timestamps are returned as UTC ISO 8601 strings.
@@ -183,7 +181,7 @@ Each result row is a JSON object keyed by column name, so a column holds whateve
 * An analysis too long to fit in the address bar cannot be shared as a link.
 * An analysis can compute at most 128 values, group by at most 64 expressions, and sort by at most 64 expressions. Each expression can be at most 4,096 characters long.
 * A time window's size and slide are whole milliseconds, and a sliding window covers at most 100 slides. `window_start` and `window_end` cannot be used as result aliases while a window is set.
-* Row, array, and map values are converted to nested JSON automatically. A column is rejected with an error that names it only if its value type has no JSON representation at all, or a constructed row has two fields with the same name.
+* Row, array, and map values are converted to nested JSON automatically. A value whose type has no JSON representation at all, or a constructed row with two fields of the same name, cannot be returned.
 
 ## Frequently Asked Questions
 
@@ -201,7 +199,7 @@ Add a time window under the grouping expressions in Analyze mode. Choose tumblin
 
 ### How many rows can an analysis return?
 
-An analysis returns 2,500 rows by default. The largest limit you can ask for is set by your deployment; asking for more is refused with a message naming the maximum.
+An analysis returns 2,500 rows by default. The largest limit you can ask for is set by your deployment.
 
 ### How do I share a Grepr analysis?
 
@@ -209,7 +207,7 @@ Copy the page URL. The link carries the dataset, time range, query, every expres
 
 ### Why can't I name a result column count?
 
-count is a reserved SQL word, so the query engine would read it as syntax rather than as an alias. Log Explorer suggests count0 instead, which is also why the default first column is named count0.
+count is a reserved SQL word, so the query engine would read it as syntax rather than as an alias. Name the column count0 or anything else that is not reserved; that is why the default first column is named count0.
 
 ### How do I turn severity numbers into names in Grepr?
 
@@ -217,4 +215,4 @@ Use SEVERITY_TEXT(severity), which names the OpenTelemetry bucket: TRACE, DEBUG,
 
 ### How do I sort an analysis by a result column?
 
-Click the column header in the results table. The rows on the page reorder immediately, without a second run. If the analysis returned its row limit, the table offers Sort on the server, which puts the sort into ORDER BY and runs the analysis again.
+Click the column header in the results table. The rows on the page reorder immediately, without a second run. If the analysis returned its row limit, use Sort on the server, which puts the sort into ORDER BY and runs the analysis again.