Logging¶

atlcli includes comprehensive JSONL logging for observability, debugging, and enterprise audit requirements.

Log Locations¶

Location	Path	Purpose
Global	`~/.atlcli/logs/YYYY-MM-DD.jsonl`	All operations
Project	`.atlcli/logs/YYYY-MM-DD.jsonl`	Project-specific operations

Both locations are written to by default when a .atlcli/ directory exists.

Viewing Logs¶

List Recent Entries¶

atlcli log list
atlcli log list --limit 50

Filter by Time¶

# Relative time
atlcli log list --since 1h
atlcli log list --since 24h
atlcli log list --since 7d

# Date range
atlcli log list --since "2025-01-01" --until "2025-01-14"

Filter by Level¶

atlcli log list --level error
atlcli log list --level warn
atlcli log list --level info
atlcli log list --level debug

Filter by Type¶

# All API logs
atlcli log list --type api

# Just command invocations
atlcli log list --type cli.command

# Sync events
atlcli log list --type sync

# Auth changes
atlcli log list --type auth

Combine Filters¶

atlcli log list --type api --level error --since 24h

Following Logs¶

Real-time log streaming:

# Follow new entries
atlcli log tail -f

# Follow with filter
atlcli log tail -f --level error

# Project logs only
atlcli log tail --project

Log Entry Details¶

View full details of a specific entry:

# Get ID from log list
atlcli log list --limit 5

# Show full entry
atlcli log show abc123-uuid-here

Clearing Logs¶

# Clear logs older than 30 days
atlcli log clear --before 30d --confirm

# Clear only global logs
atlcli log clear --before 7d --global --confirm

# Clear only project logs
atlcli log clear --before 7d --project --confirm

Log Entry Types¶

Type	Description
`cli.command`	CLI command invocations with args and flags
`cli.result`	Command completion with exit code and duration
`api.request`	Confluence/Jira API requests
`api.response`	API responses with status and duration
`sync.event`	Sync events (pull, push, conflict)
`auth.change`	Authentication changes (login, logout, switch)
`error`	Errors with stack traces and context

Log Format¶

Each entry is a JSON object:

{
  "id": "5bb8303b-08ce-4c9d-9a2e-657ca2ceaece",
  "timestamp": "2025-01-14T12:12:20.722Z",
  "level": "info",
  "type": "api.request",
  "pid": 12345,
  "sessionId": "3ea06a39-52b2-4b18-a74b-8d0e6ee02ddf",
  "data": {
    "requestId": "ada26fed-45b8-42f1-881b-2034f6f9b6bd",
    "method": "GET",
    "url": "https://company.atlassian.net/wiki/rest/api/content/123"
  }
}

Key Fields¶

Field	Description
`id`	Unique entry identifier
`sessionId`	Correlates all logs from one CLI invocation
`requestId`	Correlates API request with its response
`pid`	Process ID
`level`	error, warn, info, debug
`type`	Entry type (see above)
`data`	Type-specific payload

JSON Output¶

For scripting and analysis:

# Get raw JSON
atlcli log list --json

# Query with jq
atlcli log list --json | jq '.entries[] | select(.data.status >= 400)'

# Count errors by type
atlcli log list --level error --json | jq 'group_by(.type) | map({type: .[0].type, count: length})'

Configuration¶

Configure logging in ~/.atlcli/config.json:

{
  "logging": {
    "level": "info",
    "global": true,
    "project": true
  }
}

Options¶

Option	Values	Default	Description
`level`	off, error, warn, info, debug	`info`	Minimum level to log
`global`	true, false	`true`	Write to global log
`project`	true, false	`true`	Write to project log

Disabling Logging¶

# Single command
atlcli wiki page list --space DEV --no-log

# Globally (in config)
# Set "level": "off"

Sensitive Data Handling¶

Sensitive fields are automatically redacted:

Field	Redacted As
API tokens	`[REDACTED]`
Passwords	`[REDACTED]`
Authorization headers	`Basic [REDACTED]`

Not redacted (needed for audit):

Email addresses
Page titles
Content (for sync debugging)

Use Cases¶

Debug API Failures¶

# Find failed requests
atlcli log list --type api.response --json | \
  jq '.entries[] | select(.data.status >= 400) | {url: .data.url, status: .data.status}'

Audit Trail¶

# Who did what
atlcli log list --type cli.command --since 7d --json | \
  jq '.entries[] | "\(.timestamp): \(.data.command) \(.data.args | join(" "))"'

Performance Analysis¶

# Slow API calls
atlcli log list --type api.response --json | \
  jq '.entries[] | select(.data.duration > 1000) | {url: .data.url, duration: .data.duration}'

Correlate Request/Response¶

# Find response for a request
REQUEST_ID="ada26fed-45b8-42f1-881b-2034f6f9b6bd"
atlcli log list --json | jq ".entries[] | select(.data.requestId == \"$REQUEST_ID\")"