Glean Cli

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:

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:

Write/admin:

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_TOKEN is sensitive; never echo it, log it, or include it in error messages or commit it to a file. Use it via env var only.
• Always `--dry-run` first for writes. Any create, update, delete, verify, remind, add-items, delete-item, or report action 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.
• `--json` overrides everything. If both --json and 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 api` is the escape hatch, not the default. If a dedicated subcommand exists for what you're doing (e.g. glean search rather than glean api search), prefer it - the dedicated command has nicer ergonomics and a stable contract.
• Errors land on stderr. When piping into jq or 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 .type or guard with .document?.

Glean CLI Command Reference

Detailed flags, subcommands, and worked examples for every glean command. The authoritative source for the version installed locally is always glean schema <command> - fall back to this file when the user wants a quick reminder or you need to draft a command without an extra round-trip.

Global flags (--output, --json, --dry-run) apply to every command and are documented in SKILL.md. They are omitted from the per-command tables below to keep them focused on what's specific.

Read-only commands

glean search

Search for content across the company's indexed sources. Returns JSON.

glean search [flags] [query]

Examples:

glean search "vacation policy" | jq '.results[].document.title'

glean search --json '{
  "query":"Q1 reports",
  "pageSize":5,
  "datasources":["confluence","drive"]
}' | jq .

# Tighter result for an LLM downstream
glean search "incident response" --return-llm-content --page-size 3 \
  | jq '.results[] | {title: .document.title, content: .clusteredResults}'

glean chat

Talk to Glean Assistant. Streams an AI answer to stdout, citing the underlying documents.

glean chat [flags] [message]

Examples:

glean chat "What are the company holidays?"

glean chat --json '{
  "messages":[
    {"author":"USER","messageType":"CONTENT","fragments":[{"text":"What is our PTO policy?"}]}
  ]
}'

When chaining a chat into other tooling, set --save=false so transient programmatic queries don't pollute the user's history.

glean documents

Retrieve metadata, contents, permissions, or AI summaries for indexed documents.

glean documents <subcommand> [flags]

Examples:

glean documents summarize --json '{"documentId":"DOC_ID"}' | jq -r .summary

For get, get-by-facets, and get-permissions request body shapes (which take URL specs, facet filters, and document references respectively), run glean schema documents <subcommand> and inspect .flags."--json".schema before constructing the payload. Glean's REST surface for these endpoints accepts several alternative input shapes and the schema is the source of truth.

glean entities

Look up people, teams, and custom entities.

glean entities <subcommand> [flags]

--json is required (no positional shortcut).

Example (the only documented shape - for list, run glean schema entities list to see the supported body):

glean entities read-people --json '{"query":"smith"}' | jq '.[] | {name, email, title}'

glean messages

Retrieve a specific indexed message (Slack, Teams, etc.) by ID.

glean messages get --json '{"messageId":"MSG_ID"}' | jq .

--json is required.

glean insights

Pull search and usage analytics.

glean insights get --json '{"insightTypes":["SEARCH"]}' | jq .

--json is required. The insightTypes array drives the report shape.

glean agents

List, inspect, and run Glean AI agents (LangChain-style published workflows).

glean agents <subcommand> [flags]

Examples:

glean agents list | jq '.[] | {id, name}'

glean agents schemas --json '{"agentId":"agent_id"}' | jq .

glean agents run --json '{"agentId":"agent_id","input":{"query":"test"}}'

Inspect the agent's schemas output before constructing a run payload - agent inputs are agent-specific.

glean tools

List and run platform tools (server-side integrations exposed by Glean).

glean tools <subcommand> [flags]

glean tools list | jq '.[].name'

For run, inspect glean schema tools run to see the expected body - tool parameters are tool-specific.

glean answers (read side)

glean answers list | jq '.[] | {id, question}'
glean answers get --json '{"answerId":"ANS_ID"}' | jq .

Write / admin commands

All of these mutate state in the customer's Glean tenant. Use --dry-run first.

glean collections

Curated sets of documents.

glean collections <subcommand> [flags]

glean collections list | jq '.[] | {id, name}'
glean collections create --json '{"name":"On-call runbooks"}' --dry-run

For add-items, delete-item, update, and delete, run glean schema collections <subcommand> to confirm the request body shape before sending.

glean pins

Promote a document to the top of search results for given queries.

glean pins <subcommand> [flags]

glean pins list | jq '.[].id'

For create, update, and remove, the body shape is documented in glean schema pins <subcommand> - check it before constructing the payload.

glean shortcuts

Manage go-links (e.g. go/wiki -> an internal URL).

glean shortcuts <subcommand> [flags]

glean shortcuts list | jq '.results[].inputAlias'

glean shortcuts create --json '{
  "data":{
    "inputAlias":"runbook/oncall",
    "destinationUrl":"https://confluence.example.com/oncall"
  }
}'

Note the nested data: wrapper on create/update - easy to miss.

glean announcements

Time-bounded company announcements that surface across the Glean UI.

glean announcements <subcommand> [flags]

glean announcements create --json '{"title":"Company Update","body":"..."}' --dry-run

The schema may require additional fields (start/end timestamps, target audiences) - confirm with glean schema announcements create before sending a real announcement.

glean answers (write side)

glean answers list | jq '.[].id'

Body shapes for create, update, and delete are documented in glean schema answers <subcommand>. Run that before constructing a payload.

glean verification

Document review workflows.

glean verification <subcommand> [flags]

glean verification list | jq '.[].document.title'

For verify and remind, the body shape is in glean schema verification <subcommand> - check it first.

glean activity

Log user activity events and submit relevance feedback. Mostly used by integrations, not interactive users.

glean activity report --json '{"events":[{"action":"VIEW","url":"https://example.com"}]}'

--json is required for both subcommands. The feedback body shape is documented in glean schema activity feedback.

glean api

Raw authenticated HTTP request to any Glean REST endpoint. Use this only when no dedicated subcommand exists.

glean api <path> [flags]

Example:

glean api search --method POST \
  --raw-field '{"query":"test","pageSize":3}' \
  --no-color | jq .results