---
summary: "CLI reference for `sophiaclaw logs` (tail gateway logs via RPC)"
read_when:
  - You need to tail Gateway logs remotely (without SSH)
  - You want JSON log lines for tooling
title: "logs"
---

# `sophiaclaw logs`

Tail Gateway file logs over RPC (works in remote mode).

Related:

- Logging overview: [Logging](/logging)

## Examples

```bash
sophiaclaw logs
sophiaclaw logs --follow
sophiaclaw logs --json
sophiaclaw logs --limit 500
sophiaclaw logs --local-time
sophiaclaw logs --follow --local-time
```

Use `--local-time` to render timestamps in your local timezone.

## Subcommands

### `sophiaclaw logs cleanup`

Apply retention policies to session logs.

```bash
sophiaclaw logs cleanup [options]
```

Options:

- `--dry-run` – Preview changes without applying.
- `--agent <agentId>` – Target specific agent.
- `--force` – Skip confirmation prompt.
- `--only-compress` – Only compress files, don't delete.
- `--only-delete` – Only delete old files, don't compress.

### `sophiaclaw logs stats`

Show storage statistics for session logs.

```bash
sophiaclaw logs stats [options]
```

Options:

- `--agent <agentId>` – Target specific agent.
- `--json` – Output JSON.

### `sophiaclaw logs compress`

Compress session log files.

```bash
sophiaclaw logs compress [options]
```

Options:

- `--older-than <days>` – Compress files older than N days.
- `--agent <agentId>` – Target specific agent.
- `--include-archived` – Include archived files.

## Configuration

Log storage settings are configured in `sophiaclaw.json` under `session.logStorage`. See [Session Log Storage](/configuration/session-log-storage) for details.