| name | log-search |
| description | Search stored Docker container logs for a text query using container-log-viewer. Covers clv search CLI and the /api/logs/search HTTP endpoint. |
log-search skill
Use this skill when the user wants to:
- Search log history for an error message or keyword
- Find which containers logged a specific string
- Filter search results by level or container
- Query the search API programmatically
CLI search
clv search "<query>"
Searches all stored log lines using SQLite FTS5 full-text search.
Options:
--container <name> Limit search to one container
--level <levels> Filter by level: error,warn,info,debug
--limit <n> Max results (default 50)
--format <text|json> Output format (default: text)
Examples:
# Find all "connection refused" occurrences
clv search "connection refused"
# Errors only in the worker container
clv search "timeout" --container worker --level error
# JSON output for scripting
clv search "ECONNREFUSED" --format json
# Raise the result cap
clv search "deprecated" --limit 200
Output format
Text output columns: TIME, CONTAINER, LEVEL, MESSAGE
The query term is highlighted in the MESSAGE column (terminal: amber/bold; web UI: yellow background chip).
JSON output per result:
{
"id": 1794,
"container_name": "worker",
"ts": "2026-03-20T15:50:14.600Z",
"level": "error",
"stream": "stderr",
"msg": "Job failed: SMTP connection refused",
"raw": "{\"level\":\"error\",\"msg\":\"Job failed: SMTP connection refused\",...}"
}
HTTP API
Search endpoint
GET /api/logs/search?q=<query>[&container=<name>][&level=<levels>][&limit=<n>]
Response:
{
"query": "connection refused",
"total": 8,
"results": [
{
"id": 1201,
"container_name": "worker",
"ts": "2026-03-20T15:50:14.600Z",
"level": "error",
"stream": "stderr",
"msg": "Job failed: SMTP connection refused",
"raw": "..."
}
]
}
Other log endpoints
GET /api/logs?container=<name>[&level=<levels>][&since=<iso>][&limit=<n>]
Returns paginated log lines for a container. Use since with an ISO timestamp for pagination.
GET /api/logs/:id
Returns a single log line by ID with full raw field.
CI / scripting example
Check for any ERROR logs in the last run before promoting:
ERRORS=$(clv search "ERROR" --container api --level error --format json | jq '.total')
if [ "$ERRORS" -gt 0 ]; then
echo "Found $ERRORS errors in api container - aborting deploy"
exit 1
fi
Web UI search
Open http://127.0.0.1:3200, click "Search logs" in the sidebar.
- Type a query and press Enter or click Search
- Results show across all containers with highlighted match terms
- Use level chips to narrow results
- Click any result row to expand full JSON payload
FTS notes
- Search is case-insensitive
- Phrase search: use quotes - "connection refused"
- Prefix search: append * - "connectio*"
- The FTS index covers the
msg field only, not the raw JSON body
- Results are ordered by timestamp descending (most recent first)
