Skip to content

Usage

Prerequisites

Install grapicli and set up your credentials before running any commands. See the Installation page for full details. Quick summary:

python3.14 -m venv .venv && source .venv/bin/activate
pip install grapicli

Create a .env file in your working directory:

export GRAYLOG_URL=https://your-graylog-server
export GRAYLOG_TOKEN=your_api_token_here

Synopsis

grapicli search [OPTIONS]

Options

Flag Short Type Default Description
--source -s TEXT — Filter by source host or identifier
--message -m TEXT — Filter by message text (Lucene substring)
--limit -n INT 30 Maximum number of messages to return
--last -l INT 15 Return messages from the last N minutes
--since -S TEXT — Start of an absolute time range
--until -U TEXT — End of an absolute time range (default: now)
--help Show help and exit

Time range modes

Relative (default)

When no time flags are provided, grapicli returns messages from the last 15 minutes:

grapicli search

Use --last to change the window (in minutes):

# Last hour
grapicli search --last 60

# Last 5 minutes
grapicli search --last 5

Absolute

When --since or --until (or both) are provided, grapicli performs an absolute range search.

Accepted datetime formats:

Format Example
YYYY-MM-DD HH:MM:SS 2026-04-17 08:30:00
YYYY-MM-DDTHH:MM:SS 2026-04-17T08:30:00
YYYY-MM-DD HH:MM 2026-04-17 08:30
YYYY-MM-DD 2026-04-17

All times are interpreted as UTC.

# Since a specific time (until now)
grapicli search --since "2026-04-17 08:00:00"

# Explicit range
grapicli search --since "2026-04-17 08:00:00" --until "2026-04-17 09:00:00"

# Until a specific time (from 1 hour before)
grapicli search --until "2026-04-17 09:00:00"

Filtering

Filters use Graylog's Lucene query syntax internally. Multiple filters are combined with AND.

# By source only
grapicli search --source myserver

# By message content only
grapicli search --message "connection refused"

# Both combined
grapicli search --source myserver --message "timeout"

Controlling result count

# Return up to 100 messages
grapicli search --limit 100

# Return only 5 messages (useful for a quick check)
grapicli search --limit 5

Combining options

# Last 30 minutes, source filter, 50 results
grapicli search --last 30 --source CR16IMAGEPROD01 --limit 50

# Absolute range with message filter
grapicli search \
  --since "2026-04-17 06:00:00" \
  --until "2026-04-17 07:00:00" \
  --message "error" \
  --limit 100

Output format

Results are displayed in a Rich table with three columns:

Column Description
Timestamp UTC timestamp of the log message
Source The host or service that generated the log
Message The log message body

A summary line above the table shows the total number of server-side matches and how many are being displayed.

Query: source:"myserver"  Matches: 4821  Showing: 30/30
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Timestamp                ┃ Source     ┃ Message                            ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 2026-04-17T10:00:01.000Z │ myserver   │ Service started successfully       │
└──────────────────────────┴────────────┴────────────────────────────────────┘