CLI Reference

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. Use `--session <name>` for a specific session
`lnav-install`	Install the lnav format definition for viewing JSONL logs with lnav

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

docker-agent-tail 'api-*' --follow

Examples

docker-agent-tail --all

docker-agent-tail --compose

docker-agent-tail 'api-*'

docker-agent-tail --all --json

docker-agent-tail --all --exclude 'health' --mute 'worker'

docker-agent-tail --all --since 5m

docker-agent-tail --all --no-color > logs.txt

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.

{"ts":"2026-03-04T10:30:01.789Z","container":"api","stream":"stdout","message":"GET /api/users 200 12ms"}

{"ts":"2026-03-04T10:30:01.789Z","container":"mongodb","stream":"stdout","level":"info","msg":"Connection accepted","attr":{"remote":"192.168.1.1"}}

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 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`

Get Started

Reference

Help

Commands

Global Flags

Filter Flags

Positional Arguments

`PATTERN`

Examples

Output Files

Log Format

Exit Codes

Environment Variables

​Commands

​Global Flags

​Filter Flags

​Positional Arguments

​PATTERN

​Examples

​Output Files

​Log Format

​Exit Codes

​Environment Variables

Commands

Global Flags

Filter Flags

Positional Arguments

`PATTERN`

Examples

Output Files

Log Format

Exit Codes

Environment Variables