ottyl/SKILL.md

name, description

name	description
ottyl	Query and configure a running ottyl observability instance (logs, params, metrics, dashboards) via its MCP server.

ottyl

ottyl turns a piped command's stdout into a searchable log timeline plus ad-hoc metrics and dashboards, served from a single process. This doc covers how an agent connects to and drives a running instance.

Find a session

Each ottyl process registers itself under a name (random, e.g. comic-gazelle, unless started with --name <name>). List known sessions:

ottyl sessions
# comic-gazelle    port=51423   pid=8421

Connect an MCP client

Start the MCP server (a separate short-lived process) pointed at that session, and register it with your MCP client (e.g. Claude Code's .mcp.json):

ottyl mcp --session comic-gazelle
# or, if you already know the port:
ottyl mcp --port 51423

This exposes six tools, each a thin proxy onto the target instance's HTTP API.

Get the latest SKILL.md

This file is compiled into the ottyl binary, so a copy you have on disk can lag behind the version a running instance actually serves (e.g. after an upgrade). A running instance always serves its own current copy read-only over HTTP — fetch it directly rather than trusting a stale local file:

curl http://localhost:<port>/SKILL.md

Use the port from ottyl sessions (or the --port/--session you passed to ottyl mcp). There is no CLI subcommand for this and no way to update it at runtime — the served content only changes when the binary is rebuilt with a new SKILL.md.

Tools

query_logs

Count or read log lines matching a FilterBar query.

{ "filter": "regex(\"error\")", "count_only": true }

declare_param

Extract a named value from matching log lines.

{
  "name": "status_code",
  "message_match_regex": "status=(\\d+)",
  "capture_group": "1",
  "kind": "number"
}

declare_metric

Bucket event counts/values by label, derived from matching log lines.

{
  "name": "errors_total",
  "message_match_regex": "level=error",
  "label_params": ["status_code"]
}

create_dashboard

Create an empty dashboard in a profile (defaults to the active profile).

{ "name": "Errors" }

add_panel

Add a panel to a dashboard, or update one in place by panel_id.

{
  "dashboard_id": "<id from create_dashboard>",
  "title": "Errors over time",
  "promql": "rate(errors_total[5m])",
  "chart_type": "line"
}

get_dashboard

Read a dashboard's current panels.

{ "dashboard_id": "<id>" }