feat!: add improved logs command (#8158)

This PR replaces the separate `logs:function`, `logs:deploy`, and
`logs:edge-functions` commands with a single unified `netlify logs`
command that can pull logs from any combination of sources — functions,
edge functions, and deploys — in one invocation.

<img width="1341" height="939" alt="Screenshot 2026-04-16 at 12 08 11"
src="https://github.com/user-attachments/assets/dcdb3c85-8a95-4c21-bd70-37e51b5e3915"
/>

<img width="1341" height="939" alt="Screenshot 2026-04-16 at 12 08 33"
src="https://github.com/user-attachments/assets/e2dc2fe2-a86b-410c-8bb0-36e7c1ee3017"
/>


## Quick start

```bash
# Show function and edge function logs from the last 10 minutes (default)
netlify logs

# Last hour
netlify logs --since 1h

# Stream in real time
netlify logs --follow

# All three sources
netlify logs --source functions --source edge-functions --source deploy --since 1h
```

## Source selection with `--source`

The `--source` flag controls which log sources to include. It accepts
`functions`, `edge-functions`, and `deploy`, and can be passed multiple
times. Defaults to `functions` and `edge-functions`.

```bash
netlify logs --source functions --since 30m
netlify logs --source edge-functions --since 1h
netlify logs --source deploy --since 2h
netlify logs --source deploy --source functions --since 1h
```

## Filtering by function name

Use `--function` and `--edge-function` to narrow down to specific
functions. Both are repeatable. When either is passed without an
explicit `--source`, the corresponding source is inferred automatically.

```bash
# Specific function
netlify logs --function checkout --since 1h

# Multiple functions
netlify logs --function checkout --function cart --since 1h

# Specific edge function
netlify logs --edge-function auth --since 30m

# Mix
netlify logs --function checkout --edge-function auth --since 1h
```

## Historical vs real-time

Historical mode is the default. The command fetches logs for a time
window and prints them sorted by timestamp, with deploy logs appearing
first when the deploy source is included.

```bash
# Duration (relative to now)
netlify logs --since 1h
netlify logs --since 30m
netlify logs --since 2 hours

# Absolute timestamps
netlify logs --since 2026-04-14T00:00:00Z --until 2026-04-15T00:00:00Z

# Mix: from 2 hours ago until 30 minutes ago
netlify logs --since 2h --until 30m
```

`--since` and `--until` accept either a **duration** (e.g. `10m`, `1h`,
`24h`, `2d`, `1h30m`, `2 hours`) or an **ISO 8601 timestamp**, matching
the convention used by `docker logs` and `journalctl`. `--until`
defaults to now. When neither `--since` nor `--follow` is given, the
default is `--since 10m`.

Real-time streaming requires the `--follow` / `-f` flag, which is
mutually exclusive with `--since`/`--until`:

```bash
netlify logs --follow
netlify logs --follow --source functions --source edge-functions
```

## Scoping by deploy with `--url`

Paste a deploy URL to scope logs to that specific deploy:

```bash
# Deploy permalink (24-char hex ID)
netlify logs --function checkout --url https://507f1f77bcf86cd799439011--my-site.netlify.app --since 1h

# Branch subdomain (resolves to most recent ready deploy on that branch)
netlify logs --url https://feature-payments--my-site.netlify.app --since 1h

# Production URL or custom domain — no deploy filter
netlify logs --url https://my-site.netlify.app --since 1h
```

The URL is validated against the linked project. Mismatched URLs produce
an error with a suggested fix:

```
The URL https://feature-x--other-site.netlify.app doesn't seem to match the linked project (my-site).
Try running netlify logs --since 1h --url https://my-site.netlify.app
```

## Source indicators and legend

Each log line is prefixed with an indicator and the source name inside
square brackets, so interleaved output from different sources is easy to
scan:

```
Showing logs from functions and edge functions for the last 1h:

  𝒇   Function
  🌐  Edge function

[𝒇 scheduled] 2026-04-16T08:10:30.880Z INFO Tic tac toe {"next_run":"..."}
[𝒇 scheduled] 2026-04-16T08:10:31.496Z INFO Duration: 54.42 ms
[🌐 auth] 2026-04-16T08:11:02.331Z INFO Token validated
```

Each source gets a deterministic color from a 10-color palette
(hash-based, consistent across sessions). The legend is printed at the
top when there are results to show. In `--json` mode, no legend is
printed.

## JSON Lines output

The `--json` flag outputs one JSON object per line, suitable for piping
to `jq`, logging infrastructure, or programmatic consumption:

```bash
netlify logs --json --since 1h
```

```json
{"source":"function","name":"checkout","timestamp":"2026-04-15T17:53:57.004Z","level":"info","message":"Order 4312 placed"}
{"source":"edge-function","name":"auth","timestamp":"2026-04-15T17:53:58.221Z","level":"info","message":"Token validated"}
{"source":"deploy","name":"deploy","timestamp":"2026-04-15T17:53:59.000Z","level":"info","message":"Building site...","section":"building"}
```

The `source` field is always first. Levels are lowercase. Deploy entries
include a `section` field when available.

## Debug diagnostics

The `--debug` flag prints HTTP request URLs, response status codes, and
timing to stderr — useful for troubleshooting empty results or slow
queries:

```bash
netlify logs --debug --since 1h
```

```
[debug] → GET https://analytics.services.netlify.com/v2/sites/.../function_logs/scheduled?from=...&to=...
[debug] ← 200 OK (142ms)
```

## Migration from old commands

The old `logs:function`, `logs:deploy`, `logs:build`, `logs:functions`,
and `logs:edge-functions` commands are hidden from help and show a
migration error with a tailored suggested command:

```
`netlify logs:function` has been replaced by a more comprehensive `netlify logs` command.

To get logs for this function from the last 10 minutes, run:

  netlify logs --source functions --function my-func --since 10m

Run `netlify logs --help` to see all available options.
```

The suggested command captures any function names the user passed to the
old command and translates them to `--function` flags.

## Full flag reference

| Flag | Type | Description |
|---|---|---|
| `-s, --source <type>` | repeatable enum: `functions`,
`edge-functions`, `deploy` | Log sources to include. Defaults to
`functions` + `edge-functions` |
| `--function <name>` | repeatable string | Filter to specific functions
by name |
| `--edge-function <name>` | repeatable string | Filter to specific edge
functions by name or path |
| `--since <time>` | duration or ISO 8601 | Start of the historical
window. Defaults to `10m` |
| `--until <time>` | duration or ISO 8601 | End of the historical
window. Defaults to now |
| `-f, --follow` | boolean | Stream in real time (mutually exclusive
with `--since`/`--until`) |
| `-u, --url <url>` | string | Scope to a specific deploy |
| `-l, --level <levels>` | repeatable string | Filter by log level |
| `--json` | boolean | Output as JSON Lines |
| `--debug` | boolean | Print HTTP diagnostics to stderr |

Author: eduardoboucas

docs/commands/logs.md

@@ -7,7 +7,7 @@ sidebar:
 # `logs`
 
 <!-- AUTO-GENERATED-CONTENT:START (GENERATE_COMMANDS_DOCS) -->
-Stream logs from your project
+View logs from your project
 
 **Usage**
 
@@ -17,71 +17,32 @@ netlify logs
 
 **Flags**
 
+- `edge-function` (*string*) - Filter to specific edge functions by name or path
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
+- `follow` (*boolean*) - Stream logs in real time instead of showing historical logs
+- `function` (*string*) - Filter to specific functions by name
+- `json` (*boolean*) - Output logs as JSON Lines
+- `level` (*string*) - Log levels to include. Choices are: trace, debug, info, warn, error, fatal
+- `since` (*string*) - Start of the historical log window. Accepts a duration (e.g. 10m, 1h, 24h) or an ISO 8601 timestamp. Defaults to 10m
+- `source` (*functions | edge-functions | deploy*) - Log sources to include. Defaults to functions and edge-functions
+- `until` (*string*) - End of the historical log window. Accepts a duration or an ISO 8601 timestamp (defaults to now)
+- `url` (*string*) - Show logs for the deploy behind the given URL. Supports deploy permalinks and branch subdomains
 - `debug` (*boolean*) - Print debugging information
 - `auth` (*string*) - Netlify auth token - can be used to run this command without logging in
 
-| Subcommand | description  |
-|:--------------------------- |:-----|
-| [`logs:deploy`](/commands/logs#logsdeploy) | Stream the logs of deploys currently being built to the console  |
-| [`logs:function`](/commands/logs#logsfunction) | Stream netlify function logs to the console  |
-
-
 **Examples**
 
 ```bash
-netlify logs:deploy
-netlify logs:function
-netlify logs:function my-function
-```
-
----
-## `logs:deploy`
-
-Stream the logs of deploys currently being built to the console
-
-**Usage**
-
-```bash
-netlify logs:deploy
-```
-
-**Flags**
-
-- `filter` (*string*) - For monorepos, specify the name of the application to run the command in
-- `debug` (*boolean*) - Print debugging information
-- `auth` (*string*) - Netlify auth token - can be used to run this command without logging in
-
----
-## `logs:function`
-
-Stream netlify function logs to the console
-
-**Usage**
-
-```bash
-netlify logs:function
-```
-
-**Arguments**
-
-- functionName - Name of the function to stream logs for
-
-**Flags**
-
-- `filter` (*string*) - For monorepos, specify the name of the application to run the command in
-- `level` (*string*) - Log levels to stream. Choices are: trace, debug, info, warn, error, fatal
-- `debug` (*boolean*) - Print debugging information
-- `auth` (*string*) - Netlify auth token - can be used to run this command without logging in
-
-**Examples**
-
-```bash
-netlify logs:function
-netlify logs:function my-function
-netlify logs:function my-function -l info warn
+netlify logs
+netlify logs --since 1h
+netlify logs --source functions --function checkout --since 24h
+netlify logs --source edge-functions --since 30m
+netlify logs --source deploy --source functions --since 1h
+netlify logs --follow
+netlify logs --follow --source functions --source edge-functions
+netlify logs --json --since 1h
+netlify logs --url https://my-branch--my-site.netlify.app --since 1h
 ```
 
----
 
 <!-- AUTO-GENERATED-CONTENT:END -->

docs/index.md

@@ -135,13 +135,7 @@ Login to your Netlify account
 
 ### [logs](/commands/logs)
 
-Stream logs from your project
-
-| Subcommand | description  |
-|:--------------------------- |:-----|
-| [`logs:deploy`](/commands/logs#logsdeploy) | Stream the logs of deploys currently being built to the console  |
-| [`logs:function`](/commands/logs#logsfunction) | Stream netlify function logs to the console  |
-
+View logs from your project
 
 ### [open](/commands/open)
 

package-lock.json

@@ -138,6 +138,7 @@
     "p-map": "7.0.3",
     "p-wait-for": "6.0.0",
     "parallel-transform": "1.2.0",
+    "parse-duration": "^2.1.6",
     "parse-github-url": "1.0.3",
     "pg": "8.20.0",
     "prettyjson": "1.2.5",