stare

Python library and CLI for the CERN ATLAS Glance/Fence API.

Installation

python -m pip install stare

Authentication

stare uses PKCE (no passwords stored). Run once to authenticate:

stare auth login

Your browser will open CERN SSO. After approval, tokens are stored locally and refreshed automatically.

CLI usage

# Search analyses — Rich table in terminal, JSON when piped
stare analysis search
stare analysis search --query 'referenceCode = ANA-HION-2018-01'
stare analysis search -q 'keywords contain Higgs' --limit 20
stare analysis search -q 'shortTitle = "Phase Closed"'

# Pipe to jq for field selection (JSON is auto-emitted)
stare analysis search | jq '.results[].referenceCode'
stare analysis search -q 'referenceCode contain HION' \
  | jq -r '.results[] | select(.status == "Active") | .referenceCode'

# Search papers
stare paper search --query 'referenceCode = HDBS-2018-33'

# Get individual resources
stare analysis get ANA-HION-2018-01
stare paper get HDBS-2018-33

# CONF notes / PUB notes
stare confnote get ATLAS-CONF-2024-001
stare pubnote get ATL-PHYS-PUB-2024-001

# Plots
stare plot search --query 'referenceCode = PLOT-MUON-2018-08'
stare plot get PLOT-MUON-2018-08

# List metadata
stare leadinggroups search
stare subgroups search

# Auth management
stare auth login
stare auth logout
stare auth status

# Cache management
stare cache info
stare cache clear --yes

Output is a Rich table when stdout is a terminal and JSON when piped or redirected. Use --json / --no-json to override. Commands that expose --no-cache bypass the 8-hour on-disk response cache for that invocation.

Library usage

from stare import Glance

g = Glance()

# Search analyses
result = g.analyses.search(query="referenceCode = ANA-HION-2018-01")
print(f"Found {result.number_of_results} analyses")
for analysis in result.results:
    print(analysis.reference_code, analysis.short_title)

# Search papers
paper_result = g.papers.search(query="referenceCode = HDBS-2018-33")
print(f"Found {paper_result.number_of_results} papers")
for paper in paper_result.results:
    print(paper.reference_code, paper.short_title)

# Fetch individual records (search-based under the hood)
analysis = g.analyses.get("ANA-HION-2018-01")
paper = g.papers.get("HDBS-2018-33")
conf_note = g.confnotes.get("ATLAS-CONF-2024-001")
pub_note = g.pubnotes.get("ATL-PHYS-PUB-2024-001")
plot = g.plots.get("PLOT-MUON-2018-08")
leadinggroups = g.leadinggroups.search(query="name = SUSY")

Use as a context manager for explicit connection lifecycle:

with Glance() as g:
    result = g.analyses.search(query="status = Active")

Inject a token directly (useful in CI/automated scripts):

g = Glance(token="your-access-token")

Configuration

Override defaults via environment variables:

Development

git clone https://github.com/kratsg/stare
cd stare
pixi install
pixi run pre-commit-install
pixi run stare auth login
pixi run test