# Logcli

> Query Loki logs using local logcli when available, with grafana/logcli Docker fallback. Use when you need to search logs, list labels, or inspect log series from a Grafana Loki instance.

- **Type:** Skill
- **Install:** `agentstack add skill-vinitu-logcli-skill-logcli-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vinitu](https://agentstack.voostack.com/s/vinitu)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vinitu](https://github.com/vinitu)
- **Source:** https://github.com/vinitu/logcli-skill

## Install

```sh
agentstack add skill-vinitu-logcli-skill-logcli-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Loki LogCLI Skill

Use this skill when the task is about querying Grafana Loki logs.

## Overview

- Public interface: `scripts/commands/logs/*.sh`
- Compatibility wrapper: `scripts/logcli.sh`
- Internal helpers: `scripts/_lib/common.sh`
- Runtime: local `logcli` first, Docker fallback second
- Output: JSON by default, with streamed logs for `query.sh`

## Main Rule

Use only `scripts/commands/logs/*.sh`.
Do not call `scripts/_lib/common.sh` or backend commands directly.

## Requirements

- Explicit `LOKI_URL` value passed to the command
- `bash` 4.0+ (`brew install bash` on macOS)
- `jq` (optional, for JSON array formatting)

The runtime chooses local `logcli` first and Docker second. The agent does not need to check that manually.

## Quick Start

```bash
LOKI_URL=https://loki.example.com \
~/.agents/skills/logcli/scripts/commands/logs/labels.sh --since 1h

LOKI_URL=https://loki.example.com \
~/.agents/skills/logcli/scripts/commands/logs/query.sh '{job="app"}' --since 1h
```

## Public Interface

- `scripts/commands/logs/query.sh`
- `scripts/commands/logs/labels.sh`
- `scripts/commands/logs/label-values.sh`
- `scripts/commands/logs/series.sh`

`scripts/logcli.sh` is a compatibility wrapper for older automation. Prefer the public commands above in new work.

## Output Rules

- `query.sh` writes log lines to stdout and a JSON status envelope to stderr.
- `labels.sh`, `label-values.sh`, and `series.sh` write JSON to stdout.
- Success output includes `backend`, which shows which runtime handled the command.
- Failures write JSON to stderr and return a non-zero exit code.

## Commands

### query

Run a LogQL query with auto-chunking.

```bash
LOKI_URL=https://loki.example.com \
scripts/commands/logs/query.sh '{job="app"}' --since 1h
scripts/commands/logs/query.sh '{job="app", level="error"}' --since 30m --url https://loki.example.com
LOKI_URL=https://loki.example.com \
scripts/commands/logs/query.sh '{job="app"}' --from 2026-03-18T06:00:00Z --to 2026-03-18T08:00:00Z
LOKI_URL=https://loki.example.com \
scripts/commands/logs/query.sh '{job="app"}' --since 1h --output raw
LOKI_URL=https://loki.example.com \
scripts/commands/logs/query.sh '{job="app"}' --since 1h --limit 1000
```

Flags:
- `--since ` — relative time range: `5m`, `1h`, `6h` (default: `1h`)
- `--from ` — absolute start time
- `--to ` — absolute end time
- `--limit ` — max lines per chunk (default: `5000`)
- `--output ` — logcli output mode: `raw`, `jsonl`, `default` (default: `jsonl`)
- `--url ` — direct Loki URL (overrides `LOKI_URL`)

Output: log lines to stdout, JSON status to stderr.

### labels

List available label names.

```bash
LOKI_URL=https://loki.example.com \
scripts/commands/logs/labels.sh --since 1h
scripts/commands/logs/labels.sh --since 1h --url https://loki.example.com
```

Output: `{"success":true,"command":"labels","backend":"local","results":["label1","label2"]}`

### label-values

List values for a specific label.

```bash
LOKI_URL=https://loki.example.com \
scripts/commands/logs/label-values.sh job --since 1h
scripts/commands/logs/label-values.sh type --since 1h --url https://loki.example.com
```

Output: `{"success":true,"command":"label-values","backend":"local","label":"job","results":["app","nginx"]}`

### series

List log series matching a selector.

```bash
LOKI_URL=https://loki.example.com \
scripts/commands/logs/series.sh '{job="app"}' --since 1h
scripts/commands/logs/series.sh '{job="nginx"}' --since 30m --url https://loki.example.com
```

Output: `{"success":true,"command":"series","backend":"local","selector":"{job=\"app\"}","results":[...]}`

## Environment Configuration

Config resolution order: CLI flags → explicit `LOKI_URL` environment variable.
Backend resolution order: `LOGCLI_BIN` → `logcli` from `PATH` → Docker fallback.
Chunk limits can come from `LOKI_CHUNK_SECONDS`.
The shell wrappers do not read `.env` by themselves. The agent should find the needed Loki URL and pass it as `LOKI_URL` together with the command.

For custom Loki instances:
```bash
scripts/commands/logs/labels.sh --url https://my-loki:3100 --since 1h
```

Example values:
```bash
LOKI_URL=https://loki.example.com
LOKI_CHUNK_SECONDS=3600
```

## Time Ranges and Auto-Chunking

Each environment has a max query window. If your time range exceeds it, the script automatically splits into sequential chunks.

Example: querying 3 hours with `LOKI_CHUNK_SECONDS=3600` runs 3 sequential queries.

## Output Contract

### query command
- **stdout**: raw log lines from logcli (for piping/grepping)
- **stderr**: JSON status: `{"success":true,"query":"...","chunks":1,"chunk_limit":"1h","backend":"local"}`

### labels, label-values, series commands
- **stdout**: JSON envelope: `{"success":true,"command":"...","backend":"local","results":[...]}`

### errors (all commands)
- **stderr**: `{"success":false,"error":"descriptive message"}`
- Exit code: non-zero

## Safety Boundaries

- All operations are read-only (Loki queries only).
- No write operations exist.
- No query results are cached or stored.
- Loki URLs should be passed as env vars, not hardcoded into commands.
- `scripts/_lib/common.sh` is internal and not part of the public contract.
- If local `logcli` is missing, Docker is the only supported fallback.

## References

- `references/logql-cheatsheet.md` for LogQL syntax and common patterns
- [LogQL documentation](https://grafana.com/docs/loki/latest/query/)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vinitu](https://github.com/vinitu)
- **Source:** [vinitu/logcli-skill](https://github.com/vinitu/logcli-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vinitu-logcli-skill-logcli-skill
- Seller: https://agentstack.voostack.com/s/vinitu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.