Glean PowerShell Module

A complete, idiomatic PowerShell client for the published Glean REST APIs (the Client API and the Indexing API) from the gleanwork/open-api specification: 111 operations (68 client + 43 indexing), every published operation except the one the upstream overlay marks for removal. Glean ships official SDKs for Python, TypeScript, Java, and Go; this fills the PowerShell gap.

The module is generated from the OpenAPI specs by a deterministic Python generator and layered over a small hand-written runtime, so it can be regenerated whenever the spec changes. A data-driven test suite proves the generated surface matches the spec by contract (parameters, required flags, media types, HTTP method/path/body), not just by file count.

Getting started

1. Prerequisites

PowerShell 7.2 or newer (pwsh). Check with pwsh -v. If you do not have it:

• Windows: winget install Microsoft.PowerShell
• macOS: brew install --cask powershell
• Linux: see https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-linux

2. Install the module

Pick one.

From a release package (for end users). Download Glean-<version>.zip and SHA256SUMS, then:

pwsh ./install.ps1 -PackagePath ./Glean-<version>.zip      # verifies the SHA256, then installs

This installs into your user module path so Import-Module Glean works from any session. Add -RegisterMcp to also wire up the MCP server for Claude Code.

From source (for development). Run the test suite and import in place:

./bootstrap.sh        # one-time: local PowerShell 7 + Pester + PSScriptAnalyzer + Python deps
pwsh ./build.ps1      # regenerate from specs, import, run all tests

Import-Module ./Glean/Glean.psd1

3. Connect

Choose the auth mode that matches your deployment (full detail in Authentication):

# A) API token (REST API; enables all typed cmdlets)
Connect-Glean -Instance <your-instance> -Token (Read-Host -AsSecureString)
#    <your-instance> expands to https://<your-instance>-be.glean.com. Or use -BaseUrl, or $env:GLEAN_API_TOKEN.

# B) Browser single sign-on (for an endpoint behind Okta or similar, with no API token)
Connect-Glean -CookieAuth -WebAppUrl https://<your-glean-host>
#    A browser opens; sign in; the session is captured and stored encrypted for reuse.

4. Make a call

For the common tasks, use the friendly cmdlets. They take plain arguments, return clean output, and work the same whether you connected with a token or with SSO:

Invoke-GleanChat 'Summarize the Q3 roadmap'            # returns the answer text
Search-Glean 'onboarding policy'                        # returns Title / Url / Snippet objects
Search-Glean 'incident runbook' -PageSize 25 | Format-Table Title, Url

Disconnect-Glean

That is the whole everyday surface. Under the hood, the full typed API is also there when you need it: every spec operation is a Verb-Noun cmdlet (token mode) plus a dotted alias matching the official SDK name, e.g. Search-GleanSearch / Glean.client.search.query, and New-GleanChat -Body @{...} for full control of the request shape. List everything with Get-Command -Module Glean; read help with Get-Help <cmdlet> -Examples.

Authentication

Two auth modes, both fully parameter driven (no endpoints, domains, versions, or paths are hardcoded):

Token uses a bearer API token against the REST API and enables the full typed cmdlet surface.

Connect-Glean -Instance acme -Token (Read-Host -AsSecureString)   # or -BaseUrl, or $env:GLEAN_API_TOKEN

Cookie / SSO is for an endpoint protected by an identity provider that does not issue API tokens. A browser window opens for you to sign in; the session is captured and stored encrypted, then reused (including headless, by the MCP server). Cookie mode targets the web-client API through Invoke-GleanWebRequest.

Connect-Glean -CookieAuth -WebAppUrl https://<your-glean-host>
Search-Glean 'onboarding'          # same friendly cmdlets work over SSO
Invoke-GleanChat 'What changed in the onboarding policy?'

Test-GleanConnection               # probe the session
Update-GleanAuth                   # re-sign-in to refresh an expired session

For web-client endpoints without a friendly wrapper, Invoke-GleanWebRequest -Endpoint <name> -Body @{ ... } is the low-level escape hatch.

Browser capture defaults to the DevTools pipe transport, which opens no network port. The loopback TCP transport is opt-in (-AllowUnsafeDebugPort), warns, and is refused in headless contexts. Captured sessions and tokens are stored with owner-only permissions under your user config directory, never in this repo. See SECURITY.md for the full model.

The typed REST cmdlets are gated off in cookie mode because their request shapes are verified only against the REST API; use Invoke-GleanWebRequest for the web-client API.

Install for others

# Build a versioned, checksummed package
pwsh ./Build-GleanPackage.ps1            # writes dist/Glean-<version>.zip + dist/SHA256SUMS + dist/install.ps1

# On the target machine: download the zip and SHA256SUMS, then verify and install
pwsh ./install.ps1 -PackagePath ./Glean-<version>.zip   # verifies SHA256 before copying; -RegisterMcp to wire up Claude Code

install.ps1 refuses to install a package whose SHA256 does not match. Prefer this download-then-verify flow over any remote one-liner.

How cmdlets map to the API

• Naming follows Glean's own Speakeasy method/group metadata, mapped to approved PowerShell verbs (create→New, delete→Remove, update→Set, list/get→Get, query/search→Search/Find, index→Add, …). Names and aliases are guaranteed unique.
• Parameters mirror the spec: path/query/header parameters and request-body fields are all bindable, with required flags honored. Two parameter sets are offered for body-bearing operations: individual Fields parameters, or a single -Body hashtable sent verbatim (use -Body for oneOf/anyOf shapes and deeply nested objects).
• Mutating operations (POST/PUT/PATCH/DELETE) support -WhatIf/-Confirm.
• Retries: HTTP 429/503 are retried automatically only for idempotent operations; non-idempotent calls require -RetryUnsafe to opt in (avoids duplicating side effects).
• Pagination: cursor-paginated list operations accept -All to follow the cursor and return the full result set. Per-operation cursor/field metadata is baked in from the spec.
• -Raw returns the undeserialized response on any cmdlet.

Layout

Glean/                 # the importable module
  Glean.psd1           # manifest (generated)
  Glean.psm1           # loader + alias registration
  Private/             # hand-written runtime (HTTP, auth, retry, paging, query/error handling)
  Public/Client/       # 68 generated client cmdlets
  Public/Indexing/     # 43 generated indexing cmdlets
  Public/Connect-Glean.ps1, Disconnect-Glean.ps1, Get-GleanConnection.ps1
generator/             # the spec-driven generator (Python) + vendored specs + contract.json
tests/                 # Pester: Contract (the fidelity gate), Naming, Module, Runtime

Regenerating after a spec update

# refresh the vendored specs from gleanwork/open-api, then:
pwsh ./build.ps1       # regenerate + test; the contract gate catches any drift

The vendored specs live in generator/specs/ (pinned for reproducible builds).

Tests

pwsh ./build.ps1 runs the Pester suites:

• Contract: the fidelity gate. 111 operations covered; every spec parameter/body field is bindable; required flags honored; and (with the HTTP layer mocked) every cmdlet issues the expected method, path, and body.
• Naming: no duplicate function names, aliases, or case-insensitive parameter collisions.
• Module: valid manifest, approved verbs (PSScriptAnalyzer), comment-based help present.
• Runtime: auth header, query serialization (style/explode), idempotent-only retry, -WhatIf, error shaping, and -All paging, exercised through real cmdlets.
• Provider / CookieAuth / SecretStore / Lifecycle: token-vs-cookie request shaping, the cookie-mode gate, browser-capture policy (pipe default, no port; unsafe port refused headless) with the browser/CDP boundary mocked, encrypted secret store with permission enforcement, and the session-expiry path including the MCP fail-closed startup.
• Install: the installer rejects a tampered package and dry-run installs a good one.

MCP server (PowerShell)

mcp/ contains a Glean MCP server written entirely in PowerShell, layered on this module, a from-scratch replication of the official @gleanwork MCP server. It speaks JSON-RPC 2.0 over stdio and exposes Glean as tools to Claude Code (or any MCP host):

Tool	Backing cmdlet
glean_search	Search-GleanSearch
glean_chat	New-GleanChat
glean_read_document	Get-GleanDocument
glean_people_search	New-GleanEntity
glean_invoke (opt-in)	any of the 111 cmdlets

Register it with Claude Code:

GLEAN_INSTANCE=acme GLEAN_API_TOKEN=*** \
  claude mcp add glean -- pwsh -NoProfile -File "$PWD/mcp/Start-GleanMcpServer.ps1"

Env: GLEAN_INSTANCE (or GLEAN_BASE_URL) and GLEAN_API_TOKEN (token scopes: MCP, SEARCH, CHAT, DOCUMENTS, ENTITIES, …). Set GLEAN_MCP_ALLOW_INVOKE=1 to expose the generic glean_invoke tool that can call any operation in the module. stdout carries only protocol messages; all logging goes to stderr. Covered by tests/Mcp.Tests.ps1 (protocol, tool dispatch with mocked HTTP, and a real stdin/stdout subprocess smoke test).

Notes

This is a community-generated client, not an official Glean product. It targets PowerShell 7.2+.