logcli (Loki): Usage, Options & Common CI Errors
logcli runs LogQL queries against a Grafana Loki instance from the shell.
logcli is the command-line client for Loki, letting a pipeline grep distributed logs by label. The usual stumbles are the LogQL stream selector syntax and pointing --addr at the right Loki.
What it does
logcli sends LogQL queries to a Loki HTTP endpoint and prints matching log lines (or metric results for aggregations). It supports range and instant queries, label discovery, and tailing.
Common usage
logcli query '{app="api"}' --addr=http://loki:3100
logcli query '{app="api"} |= "ERROR"' --limit=100 --since=1h
logcli instant-query 'sum(rate({app="api"}[5m]))' --addr=http://loki:3100
logcli labels --addr=http://loki:3100
logcli query '{job="ci"}' --addr=http://loki:3100 --output=jsonlOptions
| Flag | What it does |
|---|---|
| --addr <url> | Loki server URL (or $LOKI_ADDR) |
| --limit <N> | Max number of entries to return |
| --since <dur> | Look back this far (e.g. 1h, 15m) |
| --from / --to | Explicit RFC3339 time range |
| --output <fmt> | default | raw | jsonl |
| instant-query | Evaluate a metric query at one instant |
Common errors in CI
"parse error ... queries require at least one regexp or equality matcher" means the LogQL stream selector is empty or wrong - it must include a label matcher like {app="api"}, not a bare filter. "Error response from server: ... 401" or "no org id" means missing auth/tenant headers - set --addr with credentials or pass -X-Scope-OrgID via --org-id. "connection refused" → wrong --addr. An empty result set exits 0, so "no logs" does not fail a check on its own.