# Time syntax

Commands that accept `--start` and `--end` (`cx logs`, `cx spans`, `cx dataprime query`, `cx metrics query-range`, `cx incidents list`) support the following time expressions. `cx metrics query` uses `--time` for a single instant instead.

## Formats

| Format | Example | Description |
|---|---|---|
| `now` | `now` | Current UTC time |
| Relative | `now-1h` | Subtract a duration from now |
| Relative with spaces | `now - 3d` | Spaces around `-` are allowed |
| ISO 8601 / RFC 3339 | `2024-01-01T00:00:00Z` | Absolute UTC timestamp |

## Duration tokens

Relative expressions use [humantime](https://docs.rs/humantime) duration syntax:

| Token | Meaning |
|---|---|
| `s` | Seconds |
| `m` | Minutes |
| `h` | Hours |
| `d` | Days |
| `w` | Weeks |

Compound durations are supported: `1h30m`, `2d12h`.

## Defaults by command

| Command | `--start` default | `--end` default |
|---|---|---|
| `cx logs` | `now-1h` | `now` |
| `cx spans` | `now-1h` | `now` |
| `cx dataprime query` | `now-1h` | `now` |
| `cx metrics query-range` | `now-1h` | `now` |
| `cx incidents list` | Not set | Not set |
| `cx metrics query` | Uses `--time` (defaults to `now`) | N/A |

## Examples

```bash
# Last hour (default)
cx logs 'filter $m.severity == ERROR'

# Last 6 hours
cx logs 'filter $m.severity == ERROR' --start now-6h

# Specific time window
cx logs 'filter $m.severity == ERROR' \
  --start 2024-01-01T00:00:00Z \
  --end 2024-01-01T01:00:00Z

# Last 3 days of spans for a specific service
cx spans "filter \$l.serviceName == 'checkout'" --start now-3d
```
