sammcj Glean CLI
glean is a local CLI that authenticates to a company's Glean instance and exposes its REST API. It can search the corporate index, talk to Glean Assistant, look up people, fetch and summarise documents, and manage Glean-side resources (collections, pins, go-links, announcements, curated answers, agents, verification workflows).
Output is JSON on stdout, errors on stderr, exit code reflects success. This makes the CLI ideal for piping into jq.
Prerequisite check
Before using anything in this skill, make sure the binary is on $PATH:
command -v glean
The glean CLI command is provided by brew install gleanwork/tap/glean-cli
If the command isn't found, you shoulkd ask the user if they wish you to install it for them.
If unauthenticated (run glean auth status upon authentication errors) and the user is at a terminal: glean auth login (browser OAuth). For CI or scripts, set GLEAN_API_TOKEN and GLEAN_HOST env vars instead - credentials resolve in the order: env vars -> system keyring -> ~/.glean/config.json.
Always introspect first
glean schema is the source of truth for commands and flags - Glean ships updates, and the schema reflects whatever version is installed locally. Before invoking a command you haven't used in this session, run:
glean schema <command> # full machine-readable schema for one command
glean schema | jq '.commands' # list every available command
The reference file in this skill (references/commands.md) is a fast lookup, but if glean schema disagrees, schema wins.
Calling pattern
glean <command> [subcommand] [flags]
Three flags are global and worth knowing up front:
| Flag | Purpose |
|---|---|
--output <json|ndjson|text> |
Default json. Use ndjson when streaming results to a pipeline. |
--json '<payload>' |
Send a complete JSON request body. Overrides every other flag - use this for any non-trivial request, the schema documents the body shape. |
--dry-run |
Print the request that would be sent, send nothing. Always use this before any create/update/delete operation. |
Short positional flags exist for ergonomic queries (glean search "vacation policy", glean chat "what are the holidays?"), but anything beyond a single string should go through --json.
Commands at a glance
Read-only:
| Command | Use for |
|---|---|
glean search |
Find documents across all enterprise sources. |
glean chat |
Ask Glean Assistant a question; streams an AI answer. |
glean documents |
Fetch a doc's metadata, content, permissions, or AI summary. |
glean entities |
Look up people, teams, or custom entities. |
glean messages |
Read a specific Slack/Teams message by ID. |
glean insights |
Pull search/usage analytics. |
glean agents |
List, inspect, and run Glean AI agents. |
glean tools |
List and run Glean platform tools. |
glean answers |
List/get curated Q&A pairs. |
Write/admin:
| Command | Use for |
|---|---|
glean collections |
Create/update/delete document collections; add/remove items. |
glean pins |
Promote a document to the top of results for given queries. |
glean shortcuts |
Manage go-links (e.g. go/wiki). |
glean announcements |
Create/update/delete time-bounded company announcements. |
glean answers |
Create/update curated answers. |
glean verification |
Mark documents verified; send verification reminders. |
glean activity |
Log user activity events; submit relevance feedback. |
glean api |
Raw authenticated HTTP call to any Glean REST endpoint (escape hatch). |
For flag-level detail and worked examples on any of these, read references/commands.md - it's organised by command in the same order as the tables above.
Common workflows
Search and pipe into jq. Search returns JSON with a results array; each result has a document with title, url, id, snippets, etc.
glean search "incident response runbook" | jq '.results[] | {title: .document.title, url: .document.url}'
Find then summarise. Combine search with the summarise subcommand:
DOC_ID=$(glean search "Q1 OKRs" | jq -r '.results[0].document.id')
glean documents summarize --json "{\"documentId\":\"$DOC_ID\"}" | jq -r .summary
Ask a question. For any "what does our company say about X" question, prefer glean chat over glean search - Glean Assistant cites the underlying documents in its response.
glean chat "How do I expense international travel?"
Look up a person.
glean entities read-people --json '{"query":"Jane Smith"}' | jq '.[0] | {name, email, title, department}'
Gotchas
- Don't echo tokens.
GLEAN_API_TOKENis sensitive; neverechoit, log it, or include it in error messages or commit it to a file. Use it via env var only. - Always
--dry-runfirst for writes. Anycreate,update,delete,verify,remind,add-items,delete-item, orreportaction sends data into the customer's Glean tenant. Print the body first, get the user's confirmation if it's not their explicit ask, then send. --jsonoverrides everything. If both--jsonand individual flags are supplied, the JSON body wins - silently. Don't mix the two.- Schema, not memory. Flag names and JSON body shapes evolve between Glean releases. If you pass a body and the API rejects it, run
glean schema <command>and check the current shape rather than guessing. glean apiis the escape hatch, not the default. If a dedicated subcommand exists for what you're doing (e.g.glean searchrather thanglean api search), prefer it - the dedicated command has nicer ergonomics and a stable contract.- Errors land on stderr. When piping into
jqor another consumer, capture stderr separately so you can surface the real error message rather than a "parse error: unexpected end of JSON" downstream. - Search results aren't always document objects.
results[]may contain promoted answers, people, or pinned items - when working programmatically, branch on.typeor guard with.document?.