> ## Documentation Index
> Fetch the complete documentation index at: https://docker-agent-tail.michaelscotello.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for all docker-agent-tail commands, flags, and options.

## Commands

| Command        | Description                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `init`         | Set up AI agent config files (skills, CLAUDE.md, and agent-specific rule files)                                |
| `agent-help`   | Print a usage guide for AI coding agents to read                                                               |
| `clean`        | Remove old log sessions. Use `--retain N` to keep the last N sessions (default: 5). Use `--dry-run` to preview |
| `lnav`         | Open the latest session in [lnav](/lnav). Use `--session <name>` for a specific session                        |
| `lnav-install` | Install the lnav format definition for viewing JSONL logs with [lnav](/lnav)                                   |

```bash theme={null}
# Examples
docker-agent-tail init
docker-agent-tail clean --retain 3
docker-agent-tail clean --dry-run
docker-agent-tail lnav
docker-agent-tail lnav --session 2026-03-04-143700
docker-agent-tail lnav-install
```

## Global Flags

| Flag            | Description                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| `--all, -a`     | Discover and tail all running containers                                    |
| `--names, -n`   | Comma-separated list of container names to tail (e.g., `api,web,db`)        |
| `--compose, -c` | Tail all services in a Docker Compose project (requires docker-compose.yml) |
| `--follow, -f`  | Reattach on container restart (default: false)                              |
| `--json`        | Output logs as JSON Lines to stdout instead of human-readable format        |
| `--output, -o`  | Output directory for log files (default: `./logs`)                          |
| `--since, -s`   | Only show logs since a duration ago (e.g., `5m`, `1h`)                      |
| `--no-color`    | Disable colored output (useful for piping to files)                         |
| `--version, -v` | Show version and exit                                                       |
| `--help, -h`    | Show help message                                                           |

## Filter Flags

| Flag            | Description                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--exclude, -e` | Exclude log lines matching a regex pattern. Example: `--exclude 'health.*check'`                                      |
| `--mute, -m`    | Hide log lines matching a regex pattern from terminal output (still written to log files). Example: `--mute 'worker'` |

## Positional Arguments

### `PATTERN`

Optional glob pattern to filter containers by name. Example: `web-*` matches all containers starting with "web-".

```bash theme={null}
docker-agent-tail 'api-*' --follow
```

## Examples

<CodeGroup>
  ```bash Tail all containers theme={null}
  docker-agent-tail --all
  ```

  ```bash Docker Compose services theme={null}
  docker-agent-tail --compose
  ```

  ```bash Filter by name pattern theme={null}
  docker-agent-tail 'api-*'
  ```

  ```bash JSON Lines output to stdout theme={null}
  docker-agent-tail --all --json
  ```

  ```bash Save logs with filtering theme={null}
  docker-agent-tail --all --exclude 'health' --mute 'worker'
  ```

  ```bash Logs from the last 5 minutes theme={null}
  docker-agent-tail --all --since 5m
  ```

  ```bash Without ANSI colors theme={null}
  docker-agent-tail --all --no-color > logs.txt
  ```
</CodeGroup>

## Output Files

When using `--output` (default: `./logs`), a timestamped session directory is created with the following files:

| File                     | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `combined.jsonl`         | All logs from all containers in one JSONL file         |
| `<container-name>.jsonl` | Individual JSONL log file for each container           |
| `metadata.json`          | Session metadata (start time, command, container list) |

A `latest` symlink always points to the most recent session directory.

## Log Format

Log files use JSON Lines (`.jsonl`). Each line is a valid JSON object.

<CodeGroup>
  ```json Plain text container output theme={null}
  {"ts":"2026-03-04T10:30:01.789Z","container":"api","stream":"stdout","message":"GET /api/users 200 12ms"}
  ```

  ```json Structured JSON (merged + level normalized) theme={null}
  {"ts":"2026-03-04T10:30:01.789Z","container":"mongodb","stream":"stdout","level":"info","msg":"Connection accepted","attr":{"remote":"192.168.1.1"}}
  ```
</CodeGroup>

* **`ts`**: ISO 8601 timestamp (RFC3339Nano)
* **`container`**: Container name
* **`stream`**: `stdout` or `stderr`
* **`level`**: Normalized log level (when detected from structured JSON)
* **`message`**: Log message (plain text output only)

Structured JSON from containers is automatically merged with metadata fields. Log levels are [normalized](/lnav#level-normalization) to canonical values (`debug`, `info`, `warning`, `error`, `fatal`, `trace`).

## Exit Codes

| Code | Meaning                                          |
| ---- | ------------------------------------------------ |
| `0`  | Success                                          |
| `1`  | General error                                    |
| `2`  | No containers found matching criteria            |
| `3`  | Docker daemon error (connection failed, timeout) |
| `64` | Usage error (invalid flags or arguments)         |

## Environment Variables

| Variable      | Description                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `DOCKER_HOST` | Docker socket or daemon address. Default: `~/.docker/run/docker.sock` or `/var/run/docker.sock` |