> ## 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.

# FAQ

> Common questions about docker-agent-tail.

<AccordionGroup>
  <Accordion title="Do I need Docker running?">
    Yes, docker-agent-tail needs Docker daemon to be running and accessible. It connects to the Docker socket to list and stream container logs.
  </Accordion>

  <Accordion title="What if I don't have permission to access the Docker socket?">
    Add your user to the docker group:

    ```bash theme={null}
    sudo usermod -aG docker $USER
    ```

    Then log out and back in for the change to take effect.
  </Accordion>

  <Accordion title="Can I use this with Docker Compose?">
    Yes! Use the `--compose` flag to automatically discover and tail all services in a `docker-compose.yml` file.
  </Accordion>

  <Accordion title="What log drivers are supported?">
    docker-agent-tail works with `json-file` and `journald` log drivers. Other drivers won't support real-time streaming.
  </Accordion>

  <Accordion title="Can I filter out certain log lines?">
    Yes, use `--exclude` to skip lines matching a regex pattern. Use `--mute` to hide matching containers from terminal output while still writing them to log files.
  </Accordion>

  <Accordion title="Can I save logs to files?">
    Logs are saved automatically to the `./logs` directory (configurable with `--output`). Each session creates a timestamped directory with `combined.jsonl` and per-container `.jsonl` files. A `latest` symlink always points to the most recent session.
  </Accordion>

  <Accordion title="What's the difference between --exclude and --mute?">
    `--exclude` completely skips log lines matching the regex — they are not shown in the terminal and not written to files. `--mute` hides matching containers from terminal output but still writes their logs to files for later analysis.
  </Accordion>

  <Accordion title="What format are log files in?">
    Log files use JSON Lines (`.jsonl`) format. Each line is a valid JSON object with fields like `ts`, `container`, `stream`, and either `message` (plain text) or the original structured fields (JSON container output). Structured JSON from containers is automatically merged with metadata and levels are normalized. No special flag is needed — JSONL is the default file format.
  </Accordion>

  <Accordion title="How do I view logs interactively?">
    Use [lnav](https://lnav.org), a terminal-based log viewer. Install the format definition once with `docker-agent-tail lnav-install`, then view logs with:

    ```bash theme={null}
    lnav logs/latest/combined.jsonl
    ```

    lnav supports SQL queries, regex filtering, and color-coded log levels. See the [lnav integration guide](/lnav) for details.
  </Accordion>

  <Accordion title="How do I clean up old log sessions?">
    Use the `clean` command to remove old sessions:

    ```bash theme={null}
    # Keep the 5 most recent sessions (default)
    docker-agent-tail clean

    # Keep only the 3 most recent
    docker-agent-tail clean --retain 3
    ```
  </Accordion>

  <Accordion title="How do I filter logs by time?">
    Use `--since` with a Go duration (e.g., `5m`, `1h`, `30s`) to only show logs from that duration ago:

    ```bash theme={null}
    docker-agent-tail --all --since 5m
    ```
  </Accordion>

  <Accordion title="Does this work with TTY-attached containers?">
    Containers with TTY attached may output raw streams. docker-agent-tail detects this and handles it appropriately.
  </Accordion>

  <Accordion title="Can I use glob patterns to filter containers?">
    Yes, pass a glob pattern as an argument to match container names. For example: `web-*` matches all containers starting with "web-".
  </Accordion>

  <Accordion title="What if I have containers with the same name?">
    Docker doesn't allow duplicate container names, so this shouldn't happen. Each container must have a unique name.
  </Accordion>

  <Accordion title="Can I tail logs from a remote Docker daemon?">
    Yes! Set the `DOCKER_HOST` environment variable to connect to a remote Docker daemon.
  </Accordion>

  <Accordion title="How much disk space do logs take?">
    That depends on your containers' verbosity and how long you run docker-agent-tail. Use `--exclude` to reduce file size, and `docker-agent-tail clean` to remove old sessions.
  </Accordion>

  <Accordion title="Is there a performance impact on my containers?">
    No. docker-agent-tail reads from Docker's log buffers and doesn't interfere with container execution.
  </Accordion>

  <Accordion title="How do I stop tailing logs?">
    Press `Ctrl+C` in the terminal. This cleanly closes all log streams and exits gracefully.
  </Accordion>

  <Accordion title="Can I use this in CI/CD pipelines?">
    Yes! Use `--output` to save logs as artifacts. Use `--no-color` or `--json` for cleaner log files when piping to other tools.
  </Accordion>

  <Accordion title="Why are no logs appearing for my container?">
    Check the container's log driver: `docker inspect --format='{{.HostConfig.LogConfig.Type}}' <container>`. docker-agent-tail only works with `json-file` and `journald` drivers. Other drivers (e.g., `syslog`, `awslogs`, `fluentd`) don't support Docker's `ContainerLogs` API.
  </Accordion>

  <Accordion title="What are the 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)         |
  </Accordion>

  <Accordion title="Can I get JSON output on stdout?">
    Yes! Use the `--json` flag to output structured JSON Lines to stdout instead of human-readable format. This is useful for piping to `jq` or other tools.
  </Accordion>

  <Accordion title="How do I preview what clean will delete?">
    Use `--dry-run` to list sessions that would be deleted without actually removing them:

    ```bash theme={null}
    docker-agent-tail clean --dry-run
    docker-agent-tail clean --retain 2 --dry-run
    ```
  </Accordion>
</AccordionGroup>

***

## Still Have Questions?

Check out the [CLI reference](/cli-reference) for complete documentation, or visit the [GitHub repository](https://github.com/Mscotello/docker-agent-tail) to file an issue.