Skill: log-tailer CLI

# Skill: log-tailer CLI

## When to use

Use this skill when you need to add, remove, or list log sources, watch a live log stream from the terminal, apply level or search filters without opening the dashboard, or diagnose source connection issues.

## Prerequisites

- Node.js 20 or later
- log-tailer API server running on `http://127.0.0.1:7521` (or configured host/port)
- Docker socket at `/var/run/docker.sock` for Docker sources (optional)

## Installation

```
npm install -g log-tailer
```

Or run without installing:

```
npx log-tailer
```

The `npx log-tailer` command starts the API server and opens the dashboard. The `logtail` binary provides the CLI client.

## Quick start

```
# start the server
npx log-tailer

# add a file source
logtail add file /var/log/nginx/access.log --name nginx

# add a Docker container source
logtail add docker my-api-container --name api

# add a command source
logtail add command journalctl -- -u postgresql -f --name db-log

# watch the live stream in the terminal
logtail watch

# watch with filters
logtail watch --source api --level error
logtail watch --search "connection refused"
```

## Usage patterns

### Add a file source and watch immediately

```
logtail add file /var/log/app.log --name app && logtail watch --source app
```

### Add a Docker source with stderr disabled

```
logtail add docker my-container --name myapp --no-stderr
```

### Tail only errors across all sources

```
logtail watch --level error
```

### Tail one source at info+ with a search pattern

```
logtail watch --source api --level info --search "timeout|refused"
```

### List all sources with line counts

```
logtail list
```

### Disable a source without removing it

```
logtail disable nginx
logtail enable nginx
```

### Remove a source

```
logtail remove db-log
```

### Clear the buffer for one source

```
logtail clear nginx
```

### Apply a saved preset in watch mode

```
logtail watch --preset "Errors only"
```

## CLI reference

| Command | Description |
|---|---|
| `logtail add file <path>` | Add a file tail source |
| `logtail add docker <name-or-id>` | Add a Docker container source |
| `logtail add command <cmd> -- [args]` | Add a command source |
| `logtail list` | List all sources with status and line counts |
| `logtail watch` | Stream live logs to the terminal |
| `logtail disable <name>` | Pause a source without removing it |
| `logtail enable <name>` | Resume a paused source |
| `logtail remove <name>` | Remove a source and discard its buffer |
| `logtail clear <name>` | Clear a source buffer without removing the source |
| `logtail presets` | List saved filter presets |
| `logtail status` | Show server status and total line counts |

## Flag reference

### `logtail add file`

| Flag | Description |
|---|---|
| `--name <n>` | Display name for the source (default: filename) |
| `--format auto|json|plain` | Log format hint (default: auto) |

### `logtail add docker`

| Flag | Description |
|---|---|
| `--name <n>` | Display name for the source (default: container name) |
| `--no-stderr` | Exclude stderr stream (default: include stderr) |

### `logtail add command`

| Flag | Description |
|---|---|
| `--name <n>` | Display name for the source |
| `--no-restart` | Do not restart the command if it exits (default: restart) |
| `--stderr` | Include stderr stream (default: stdout only) |

### `logtail watch`

| Flag | Description |
|---|---|
| `--source <name>` | Filter to a single source |
| `--level trace|debug|info|warn|error|fatal` | Minimum log level to show |
| `--search <pattern>` | Regex pattern to match against the message field |
| `--preset <name>` | Apply a saved filter preset |
| `--json` | Output raw JSON log lines instead of formatted text |
| `--no-color` | Disable ANSI color output |

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `LOGTAIL_URL` | `http://127.0.0.1:7521` | URL of the log-tailer API server |
| `LOGTAIL_PORT` | `7521` | Port the server listens on (server-side) |
| `LOGTAIL_HOST` | `127.0.0.1` | Bind host for the server |
| `LOGTAIL_DATA_DIR` | `~/.logtail` | Directory for the SQLite database and config |
| `LOGTAIL_BUFFER_SIZE` | `5000` | Maximum lines per source ring buffer |
| `LOGTAIL_SSE_BATCH` | `50` | Maximum lines per SSE event |
| `NO_COLOR` | - | Disable color output in CLI (standard env var) |

Set `LOGTAIL_BUFFER_SIZE=0` to disable the in-memory buffer (lines are streamed directly, no history).

## Source types

### File

- Tails a regular file using `fs.watch` plus manual position tracking
- Supports log rotation: detects inode change and re-opens the file
- Path must be absolute. No path traversal allowed.
- File must exist at add time and be a regular file

### Docker

- Connects to the Docker daemon via the local Unix socket only
- Streams stdout and stderr from a running container
- Container is identified by name or short ID
- If the container stops, the source is marked inactive. It resumes automatically if the container restarts.
- Remote Docker hosts are not supported

### Command

- Spawns the executable using `child_process.spawn` with an explicit argument array
- Shell interpretation is never used. Pipes and redirects are not supported.
- By default, the command is restarted if it exits
- Process is killed with SIGTERM on source removal or server shutdown

## Troubleshooting

### "Cannot connect to log-tailer server"

The API server is not running. Start it with `npx log-tailer` or `node dist/server.js`.

Check the configured URL: `echo $LOGTAIL_URL`.

### "No running container found"

The container name or ID does not match any running container. Run `logtail add docker` without a name to list available containers, or check with `docker ps`.

### "Docker socket not found"

The Docker daemon is not running or the socket path is not `/var/run/docker.sock`. Docker sources are unavailable. File and command sources still work.

### "Path traversal detected"

The file path contains `..` or other traversal sequences. Use an absolute path starting from `/`.

### Source shows active but no lines arrive

For file sources: check that the process writing to the file is active and that log-tailer has read permission (`0644` or better).

For Docker sources: the container may be quiet. Run `docker logs <name> --tail 10` to verify.

For command sources: check that the command writes to stdout (not only to a file). Use `logtail watch --source <name>` to see if lines appear once the command produces output.

### Buffer shows 0 lines after add

File sources only buffer lines that arrive after the source is added. The file is tailed from the current end-of-file position. Historical lines are not loaded.

Docker sources load up to `LOGTAIL_BUFFER_SIZE` historical lines from the container's existing log output.