log-search

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)