From 0a22e712bf9f9510c969ba9510c3cb9d585b84d4 Mon Sep 17 00:00:00 2001
From: Quinn Milionis <quinn@scoutapm.com>
Date: Fri, 11 Sep 2026 10:25:14 -0700
Subject: [PATCH] 1.0 polish: structured output and command edge cases (part of
 #29)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Squashed for a clean rebase onto main after v0.5.0 landed, and reverted
the changelog.d/ fragment system in favor of a direct CHANGELOG.md edit
(dropped per team discussion — more process than this repo's PR
concurrency warrants). Functional content is unchanged from the
original review.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BK3fzED9ksTWsvoPfsEwpS
---
 .github/workflows/ci.yml        |  11 +++
 CHANGELOG.md                    |  18 ++++
 README.md                       |  36 ++++----
 cmd/anomalies.go                |  62 ++++++++++++--
 cmd/anomalies_test.go           |  44 ++++++++++
 cmd/apps.go                     |  24 ++++--
 cmd/auth.go                     |   3 +
 cmd/billing.go                  |   5 ++
 cmd/billing_test.go             |   7 ++
 cmd/endpoints.go                |  53 ++++++++++--
 cmd/errors.go                   |  35 ++++----
 cmd/insights.go                 |  85 +++++++++++++++++--
 cmd/insights_test.go            | 115 +++++++++++++++++++++++++
 cmd/jobs.go                     |  64 +++++++-------
 cmd/jobs_test.go                |  33 ++++++--
 cmd/metrics.go                  |  37 +++++++-
 cmd/metrics_test.go             |  43 ++++++++++
 cmd/root.go                     | 113 ++++++++++++++++++-------
 cmd/root_test.go                | 114 +++++++++++++++++++++++++
 cmd/setup.go                    |  18 ++--
 cmd/setup_test.go               |  44 ++++++----
 cmd/traces.go                   |  85 ++++++++++++++-----
 cmd/traces_test.go              |  27 ++++++
 cmd/usage.go                    | 138 ++++++++++++++++++++++--------
 cmd/usage_test.go               |  94 +++++++++++++++++++++
 go.mod                          |   3 +-
 go.sum                          |   2 -
 internal/api/client.go          |  22 ++++-
 internal/api/client_test.go     |  51 ++++++++++-
 internal/api/jobs_test.go       |  50 +++++++++++
 internal/api/types.go           |  23 +++++
 internal/config/config.go       |   3 +
 internal/config/config_test.go  |  13 +++
 internal/output/chart.go        |  97 ++++++++++++++-------
 internal/output/chart_test.go   | 144 ++++++++++++++++++++++++++++++++
 internal/output/progress.go     |   8 +-
 internal/output/style.go        |  14 ++++
 internal/output/table.go        |  12 ++-
 internal/output/table_test.go   |  44 ++++++++++
 internal/output/tree.go         |   6 +-
 internal/timeutil/parse.go      |  41 ++++++++-
 internal/timeutil/parse_test.go |  46 ++++++++++
 42 files changed, 1620 insertions(+), 267 deletions(-)
 create mode 100644 cmd/insights_test.go
 create mode 100644 cmd/metrics_test.go
 create mode 100644 cmd/root_test.go
 create mode 100644 cmd/traces_test.go
 create mode 100644 internal/output/chart_test.go
 create mode 100644 internal/output/table_test.go

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 65fe2cd..076ae92 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -27,4 +27,15 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: gofmt
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "Not gofmt-formatted:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+      - run: go vet ./...
+
       - uses: golangci/golangci-lint-action@v6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3e88c6a..fb21cdf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,9 +2,27 @@
 
 ## Pending
 
+### Changed
+
+- `scout usage --app <id>` (without `--by-day`) now filters to that one app instead of silently reporting every app, matching `--by-day --app <id>` (#29)
+- `scout usage --billing-period --json` now wraps the per-app result in an object carrying `billing_period` and `server_total`, so a script can tell which window it got and what the billed figure was. Without `--billing-period` the shape is unchanged (#29)
+- `scout jobs metrics --type latency --json` renames the API's `total` sub-series to `execution_time_total`, which is what it actually holds; other metric types are unchanged (#29)
+- `scout errors show` omits the `Count:` line when the API reports 0, which it does for every error group even when `errors list` shows a real count (#29)
+- `scout insights show` prints nested fields as indented `key: value` pairs and empty values as `—`, instead of leaking Go's `map[...]` and `<nil>` formatting (#29)
+
 ### Fixed
 
 - `scout setup <framework>` now links to a real docs page for every framework — the old `/docs/<framework>` URLs all 404'd because Scout's docs are organized by language (#27)
+- `-n`/`--limit` is now applied to `--json` output, not just the human table, across every list command: `apps list`, `endpoints list`, `jobs list`, `traces list`, `errors list`, `errors occurrences`, `anomalies list`, `insights list`, `insights show`, and all four `usage` modes. Totals and percentages are still computed over the full result set (#29)
+- `scout insights list` and `scout insights show` now honor `-n` at all; it previously had no effect on either (#29)
+- `scout anomalies --endpoint` now accepts a Base64 endpoint id and a plain endpoint name as well as the scoped name from `anomalies list`, instead of silently matching nothing (#29)
+- `--endpoint` and `--job` now reject a blank value client-side rather than passing it to the server (#29)
+- A malformed `--job` value, or a job class name copy-pasted without its queue, now gets a clear client-side error instead of a raw `API error (500)` (#29)
+- `scout auth logout` no longer fails on a machine with no config directory yet (#29)
+- `--from`/`--to` now reject a reversed range and unreasonably large or negative relative durations, which previously produced silently empty or nonsensical results (#29)
+- `--app 0` and negative app ids now report an invalid value instead of "no app specified" (#29)
+- `scout traces show` on a 404 now explains that background job traces have no detail endpoint (#29)
+- `scout insights show` field order is now stable; it previously ranged over a Go map and printed a different order every run (#29)
 
 ## [0.5.0] - 2026-09-10
 
diff --git a/README.md b/README.md
index d82701d..2ee6c47 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,15 @@ scout auth status
 scout auth logout
 ```
 
-Credentials are stored in `~/.config/scout-apm/config.json`. You can also set the `SCOUT_API_KEY` environment variable.
+Credentials are stored in a per-user config file whose location follows the platform convention:
+
+| Platform | Path |
+| --- | --- |
+| macOS | `~/Library/Application Support/scout-apm/config.json` |
+| Linux | `$XDG_CONFIG_HOME/scout-apm/config.json`, defaulting to `~/.config/scout-apm/config.json` |
+| Windows | `%AppData%\scout-apm\config.json` |
+
+`scout auth status` prints the path in use. You can also set the `SCOUT_API_KEY` environment variable, which takes precedence over the config file.
 
 ## Usage
 
@@ -102,24 +110,28 @@ Job IDs are in the `scout jobs list --json` output (`job_id`), or pass the job's
 ```bash
 scout traces list --endpoint YXBpL21ldHJpY3Mvc2hvdw== --app 6
 scout traces list --job ZGVmYXVsdC9NeVdvcmtlcg== --app 6
-scout traces show 12345 --app 6
+scout traces show <trace-id> --app 6
 ```
 
+Trace ids come from `scout traces list`.
+
 ### Errors
 
 ```bash
 scout errors list --app 6
-scout errors show 50560 --app 6
-scout errors occurrences 50560 --app 6
+scout errors show <error-group-id> --app 6
+scout errors occurrences <error-group-id> --app 6
 ```
 
+Error group ids come from `scout errors list`.
+
 ### Anomalies
 
 ```bash
 scout anomalies --app 6                                # List anomaly events (default: all states)
 scout anomalies --app 6 --state open                   # Only open anomalies
 scout anomalies --app 6 --metric response_time         # Filter by metric
-scout anomalies --app 6 --endpoint YXBpL21ldHJpY3M=    # Filter by endpoint
+scout anomalies --app 6 --endpoint Controller/users/index   # Filter by endpoint (a name from 'anomalies list', or a Base64 endpoint id)
 scout anomalies show 1234 --app 6                      # Detail with smart_monitor and deploy context
 ```
 
@@ -168,8 +180,7 @@ scout setup rails     # Show setup docs for a framework
 
 | Flag | Description |
 |------|-------------|
-| `--json` | Output raw JSON |
-| `--toon` | Output in [TOON](https://toonformat.dev/) format (auto-enabled when piped) |
+| `--json` | Output raw JSON (auto-enabled when piped) |
 | `--app <id>` | Application ID (or set `default_app_id` in config) |
 | `--from <time>` | Start time — relative (`1h`, `7d`, `30m`, `2w`) or ISO 8601 |
 | `--to <time>` | End time (default: now) |
@@ -178,22 +189,19 @@ scout setup rails     # Show setup docs for a framework
 
 ## LLM / Agent Usage
 
-When output is piped, Scout CLI automatically switches to [TOON](https://toonformat.dev/) format — a token-efficient structured format designed for LLM consumption. This means tools like Claude Code, scripts, and other agents get compact, parseable output by default.
+When output is piped, Scout CLI automatically switches to JSON. Tools like Claude Code, scripts, and other agents get structured, parseable output by default — no flags needed. Human-readable tables and charts are used only when writing to a terminal.
 
 ```bash
-# TOON output is automatic when piped
+# JSON output is automatic when piped
 scout apps list | llm "which app has the most endpoints?"
 
-# Force TOON in a terminal
-scout metrics get --type response_time --app 6 --toon
-
-# Use --json if you need raw JSON instead
+# Force JSON in a terminal
 scout metrics get --type response_time --app 6 --json
 ```
 
 ## Configuration
 
-Config file: `~/.config/scout-apm/config.json`
+Config file location (see [Authentication](#authentication) for the full table): `~/Library/Application Support/scout-apm/config.json` on macOS, `~/.config/scout-apm/config.json` on Linux. Run `scout auth status` to print the path in use.
 
 ```json
 {
diff --git a/cmd/anomalies.go b/cmd/anomalies.go
index eb8a4c8..643168f 100644
--- a/cmd/anomalies.go
+++ b/cmd/anomalies.go
@@ -3,6 +3,9 @@ package cmd
 import (
 	"fmt"
 	"strconv"
+	"strings"
+	"unicode"
+	"unicode/utf8"
 
 	"github.com/scoutapm/scout/internal/output"
 	"github.com/spf13/cobra"
@@ -55,27 +58,34 @@ func runAnomaliesList(cmd *cobra.Command, args []string) {
 		exitError(err.Error())
 	}
 
+	endpoint := ""
+	if cmd.Flags().Changed("endpoint") {
+		endpoint, err = resolveAnomalyEndpoint(anomaliesEndpoint)
+		if err != nil {
+			exitError(err.Error())
+		}
+	}
+
 	from, to, err := resolveTimeframe()
 	if err != nil {
 		exitError(err.Error())
 	}
 
-	events, err := client.ListAnomalyEvents(id, anomaliesState, anomaliesMetric, anomaliesEndpoint, from, to)
+	events, err := client.ListAnomalyEvents(id, anomaliesState, anomaliesMetric, endpoint, from, to)
 	if err != nil {
 		handleAPIError(err)
 		return
 	}
 
+	events, total := limitSlice(events)
+
 	if structuredOutput(events) {
 		return
 	}
 
-	total := len(events)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"ID", "State", "Metric", "Endpoint", "Started", "Z-score", "Multiplier"}
-	rows := make([][]string, limit)
-	for i := 0; i < limit; i++ {
+	rows := make([][]string, len(events))
+	for i := range events {
 		e := events[i]
 		state := anomalyState(e.Open)
 		rows[i] = []string{
@@ -90,7 +100,45 @@ func runAnomaliesList(cmd *cobra.Command, args []string) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(events), total)
+}
+
+// resolveAnomalyEndpoint accepts the endpoint forms used elsewhere in the CLI
+// and returns the scoped metric name the anomaly events API matches on.
+//
+// Anomalies are recorded against the full metric name ("Controller/users/index")
+// shown in 'scout anomalies list', while every other --endpoint flag takes the
+// Base64 URL-safe endpoint id from 'scout endpoints list'. Both are accepted
+// here, as is the plain endpoint name, so a base64 id no longer silently
+// matches nothing.
+func resolveAnomalyEndpoint(s string) (string, error) {
+	name, err := requireFlagValue("endpoint", s)
+	if err != nil {
+		return "", err
+	}
+	if !strings.Contains(name, "/") {
+		decoded, ok := decodeBase64ID(name)
+		if !ok {
+			return "", fmt.Errorf("invalid --endpoint %q — expected an endpoint name from 'scout anomalies list' (e.g. Controller/users/index) or a Base64 endpoint id from 'scout endpoints list --json'", s)
+		}
+		name = decoded
+	}
+	if hasMetricScope(name) {
+		return name, nil
+	}
+	return "Controller/" + name, nil
+}
+
+// hasMetricScope reports whether a name already carries a metric scope prefix
+// such as "Controller/" or "Job/". Endpoint names on their own are the
+// lowercase path portion ("users/index").
+func hasMetricScope(name string) bool {
+	scope, rest, ok := strings.Cut(name, "/")
+	if !ok || scope == "" || rest == "" {
+		return false
+	}
+	r, _ := utf8.DecodeRuneInString(scope)
+	return unicode.IsUpper(r)
 }
 
 func runAnomaliesShow(cmd *cobra.Command, args []string) {
diff --git a/cmd/anomalies_test.go b/cmd/anomalies_test.go
index 6598cb0..cfdfd54 100644
--- a/cmd/anomalies_test.go
+++ b/cmd/anomalies_test.go
@@ -4,8 +4,52 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
+func TestResolveAnomalyEndpoint(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{"scoped name passes through", "Controller/users/index", "Controller/users/index"},
+		{"job scope passes through", "Job/default/MyWorker", "Job/default/MyWorker"},
+		{"plain name gains the Controller scope", "users/index", "Controller/users/index"},
+		{"base64 endpoint id is decoded and scoped", "dXNlcnMvaW5kZXg=", "Controller/users/index"},
+		{"unpadded base64 id", "dXNlcnMvaW5kZXg", "Controller/users/index"},
+		{"surrounding whitespace is trimmed", "  Controller/users/index  ", "Controller/users/index"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := resolveAnomalyEndpoint(tt.input)
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, got)
+		})
+	}
+}
+
+func TestResolveAnomalyEndpointRejectsBadValues(t *testing.T) {
+	_, err := resolveAnomalyEndpoint("")
+	require.Error(t, err)
+	assert.Equal(t, "--endpoint requires a value", err.Error())
+
+	// No slash and not decodable: nothing sensible to send to the API.
+	_, err = resolveAnomalyEndpoint("not base64!!")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid --endpoint")
+}
+
+func TestHasMetricScope(t *testing.T) {
+	assert.True(t, hasMetricScope("Controller/users/index"))
+	assert.True(t, hasMetricScope("Job/default/MyWorker"))
+	assert.False(t, hasMetricScope("users/index"))
+	assert.False(t, hasMetricScope("users"))
+	assert.False(t, hasMetricScope("/leading-slash"))
+	assert.False(t, hasMetricScope("Controller/"))
+}
+
 func TestFormatMultiplier(t *testing.T) {
 	v15 := 1.5
 	v32 := 3.2
diff --git a/cmd/apps.go b/cmd/apps.go
index 425e6c5..6ebed8e 100644
--- a/cmd/apps.go
+++ b/cmd/apps.go
@@ -43,16 +43,15 @@ func runAppsList(cmd *cobra.Command, args []string) {
 		return
 	}
 
+	apps, total := limitSlice(apps)
+
 	if structuredOutput(apps) {
 		return
 	}
 
-	total := len(apps)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"ID", "Name", "Last Reported"}
-	rows := make([][]string, limit)
-	for i := 0; i < limit; i++ {
+	rows := make([][]string, len(apps))
+	for i := range apps {
 		app := apps[i]
 		lastReported := ""
 		if app.LastReportedAt != "" {
@@ -66,7 +65,7 @@ func runAppsList(cmd *cobra.Command, args []string) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(apps), total)
 }
 
 func runAppsShow(cmd *cobra.Command, args []string) {
@@ -86,6 +85,19 @@ func runAppsShow(cmd *cobra.Command, args []string) {
 		return
 	}
 
+	// The single-app payload omits last_reported_at, which the list payload
+	// carries; fill it in so 'apps show' isn't thinner than 'apps list'.
+	if app.LastReportedAt == "" {
+		if apps, listErr := client.ListApps(); listErr == nil {
+			for _, a := range apps {
+				if a.ID == app.ID {
+					app.LastReportedAt = a.LastReportedAt
+					break
+				}
+			}
+		}
+	}
+
 	if structuredOutput(app) {
 		return
 	}
diff --git a/cmd/auth.go b/cmd/auth.go
index f3c5d3b..c2ed9c9 100644
--- a/cmd/auth.go
+++ b/cmd/auth.go
@@ -199,6 +199,7 @@ func runAuthStatus(cmd *cobra.Command, args []string) {
 		"authenticated":  key != "",
 		"api_key_prefix": maskKey(key),
 		"api_url":        url,
+		"config_path":    config.Path(),
 	}
 	if cfg.DefaultAppID > 0 {
 		data["default_app_id"] = cfg.DefaultAppID
@@ -209,6 +210,7 @@ func runAuthStatus(cmd *cobra.Command, args []string) {
 
 	if key == "" {
 		fmt.Println(output.WarningStyle.Render("Not authenticated"))
+		fmt.Printf("  Config: %s\n", config.Path())
 		fmt.Println(output.DimStyle.Render("Run 'scout auth login' to authenticate"))
 		return
 	}
@@ -216,6 +218,7 @@ func runAuthStatus(cmd *cobra.Command, args []string) {
 	fmt.Println(output.SuccessStyle.Render("✓ Authenticated"))
 	fmt.Printf("  API Key: %s\n", maskKey(key))
 	fmt.Printf("  API URL: %s\n", url)
+	fmt.Printf("  Config: %s\n", config.Path())
 	if cfg.DefaultAppID > 0 {
 		fmt.Printf("  Default App: %d\n", cfg.DefaultAppID)
 	}
diff --git a/cmd/billing.go b/cmd/billing.go
index 33b4870..8dac2a9 100644
--- a/cmd/billing.go
+++ b/cmd/billing.go
@@ -137,6 +137,11 @@ func renderUsageBar(used, limit int64) string {
 	if filled < 0 {
 		filled = 0
 	}
+	// Anything under 2.5% rounds to no blocks at all, which reads as zero
+	// usage. Show one block instead so "a little" is distinguishable.
+	if filled == 0 && used > 0 {
+		filled = 1
+	}
 
 	bar := strings.Repeat("█", filled) + strings.Repeat("░", barWidth-filled)
 
diff --git a/cmd/billing_test.go b/cmd/billing_test.go
index 1404a0c..66d2cf9 100644
--- a/cmd/billing_test.go
+++ b/cmd/billing_test.go
@@ -35,6 +35,13 @@ func TestRenderUsageBarFillWidth(t *testing.T) {
 	assert.Contains(t, renderUsageBar(300, 100), "████████████████████")
 }
 
+func TestRenderUsageBarFloorsNonzeroUsage(t *testing.T) {
+	// 0.1% rounds to no filled blocks, which reads as no usage at all.
+	assert.Contains(t, renderUsageBar(1, 1000), "█░░░░░░░░░░░░░░░░░░░")
+	// True zero stays empty.
+	assert.Contains(t, renderUsageBar(0, 1000), "░░░░░░░░░░░░░░░░░░░░")
+}
+
 func TestFormatBillingDate(t *testing.T) {
 	tests := []struct {
 		input    string
diff --git a/cmd/endpoints.go b/cmd/endpoints.go
index 5648b21..248e8d0 100644
--- a/cmd/endpoints.go
+++ b/cmd/endpoints.go
@@ -1,7 +1,11 @@
 package cmd
 
 import (
+	"encoding/base64"
 	"fmt"
+	"strings"
+	"unicode"
+	"unicode/utf8"
 
 	"github.com/scoutapm/scout/internal/output"
 	"github.com/spf13/cobra"
@@ -21,7 +25,10 @@ var endpointsListCmd = &cobra.Command{
 var endpointsMetricsCmd = &cobra.Command{
 	Use:   "metrics",
 	Short: "Get endpoint-specific metrics",
-	Run:   runEndpointsMetrics,
+	Example: `  # The endpoint ID is the Base64 value at the end of the "link"
+  # field in 'scout endpoints list --json'
+  scout endpoints metrics --endpoint YXBpL21ldHJpY3Mvc2hvdw== --type response_time --app 6`,
+	Run: runEndpointsMetrics,
 }
 
 var endpointFlag string
@@ -29,7 +36,7 @@ var endpointMetricTypeFlag string
 
 func init() {
 	endpointsMetricsCmd.Flags().StringVar(&endpointFlag, "endpoint", "", "URL-encoded endpoint name")
-	endpointsMetricsCmd.Flags().StringVar(&endpointMetricTypeFlag, "type", "", "Metric type")
+	endpointsMetricsCmd.Flags().StringVar(&endpointMetricTypeFlag, "type", "", "Metric type ("+strings.Join(validMetricTypes, ", ")+")")
 	_ = endpointsMetricsCmd.MarkFlagRequired("endpoint")
 	_ = endpointsMetricsCmd.MarkFlagRequired("type")
 	endpointsCmd.AddCommand(endpointsListCmd, endpointsMetricsCmd)
@@ -58,16 +65,15 @@ func runEndpointsList(cmd *cobra.Command, args []string) {
 		return
 	}
 
+	endpoints, total := limitSlice(endpoints)
+
 	if structuredOutput(endpoints) {
 		return
 	}
 
-	total := len(endpoints)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"Name", "Resp Time", "Throughput", "Error %", "p95"}
-	rows := make([][]string, limit)
-	for i := 0; i < limit; i++ {
+	rows := make([][]string, len(endpoints))
+	for i := range endpoints {
 		ep := endpoints[i]
 		errorPct := output.FormatPercent(ep.ErrorRate)
 		errorColored := output.ErrorRateColor(ep.ErrorRate).Render(errorPct)
@@ -82,10 +88,12 @@ func runEndpointsList(cmd *cobra.Command, args []string) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(endpoints), total)
 }
 
 func runEndpointsMetrics(cmd *cobra.Command, args []string) {
+	requireValidMetricType(endpointMetricTypeFlag)
+
 	client, err := getClient()
 	if err != nil {
 		exitError(err.Error())
@@ -96,6 +104,11 @@ func runEndpointsMetrics(cmd *cobra.Command, args []string) {
 		exitError(err.Error())
 	}
 
+	endpointFlag, err := requireFlagValue("endpoint", endpointFlag)
+	if err != nil {
+		exitError(err.Error())
+	}
+
 	from, to, err := resolveTimeframe()
 	if err != nil {
 		exitError(err.Error())
@@ -114,7 +127,29 @@ func runEndpointsMetrics(cmd *cobra.Command, args []string) {
 	series := metrics.Series[endpointMetricTypeFlag]
 	summary := metrics.Summaries[endpointMetricTypeFlag]
 	unit := unitForMetricType(endpointMetricTypeFlag)
-	title := fmt.Sprintf("%s — %s", endpointMetricTypeFlag, endpointFlag)
+	title := fmt.Sprintf("%s — %s", endpointMetricTypeFlag, endpointDisplayName(endpointFlag))
 
 	fmt.Println(output.RenderChart(title, series, summary, unit))
 }
+
+// endpointDisplayName decodes a Base64 URL-safe endpoint ID back to the
+// endpoint name for display, returning the input unchanged when it isn't one.
+func endpointDisplayName(id string) string {
+	b, err := base64.URLEncoding.DecodeString(id)
+	if err != nil {
+		b, err = base64.RawURLEncoding.DecodeString(id)
+		if err != nil {
+			return id
+		}
+	}
+	name := string(b)
+	if name == "" || !utf8.ValidString(name) {
+		return id
+	}
+	for _, r := range name {
+		if !unicode.IsPrint(r) {
+			return id
+		}
+	}
+	return name
+}
diff --git a/cmd/errors.go b/cmd/errors.go
index c25a0a6..30ac0de 100644
--- a/cmd/errors.go
+++ b/cmd/errors.go
@@ -60,16 +60,15 @@ func runErrorsList(cmd *cobra.Command, args []string) {
 		return
 	}
 
+	groups, total := limitSlice(groups)
+
 	if structuredOutput(groups) {
 		return
 	}
 
-	total := len(groups)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"ID", "Name", "Count", "Status", "Last Seen"}
-	rows := make([][]string, limit)
-	for i := 0; i < limit; i++ {
+	rows := make([][]string, len(groups))
+	for i := range groups {
 		g := groups[i]
 		status := output.StatusColor(g.Status).Render(g.Status)
 		rows[i] = []string{
@@ -82,7 +81,7 @@ func runErrorsList(cmd *cobra.Command, args []string) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(groups), total)
 }
 
 func runErrorsShow(cmd *cobra.Command, args []string) {
@@ -114,7 +113,12 @@ func runErrorsShow(cmd *cobra.Command, args []string) {
 	fmt.Println(output.HeaderStyle.Render(group.Name))
 	fmt.Printf("  Message:  %s\n", group.Message)
 	fmt.Printf("  Status:   %s\n", output.StatusColor(group.Status).Render(group.Status))
-	fmt.Printf("  Count:    %d\n", group.ErrorsCount)
+	// The show payload leaves errors_count at 0 even for groups 'errors list'
+	// reports a count for. A group only exists because errors occurred, so a
+	// zero here means "not reported", not "none".
+	if group.ErrorsCount > 0 {
+		fmt.Printf("  Count:    %d\n", group.ErrorsCount)
+	}
 	fmt.Printf("  Last:     %s\n", output.FormatRelativeTime(group.LastErrorAt))
 	if group.RequestURI != "" {
 		fmt.Printf("  URI:      %s\n", group.RequestURI)
@@ -170,30 +174,25 @@ func runErrorsOccurrences(cmd *cobra.Command, args []string) {
 		return
 	}
 
+	occurrences, total := limitSlice(occurrences)
+
 	if structuredOutput(occurrences) {
 		return
 	}
 
-	total := len(occurrences)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"ID", "Time", "Location", "URI", "Message"}
-	rows := make([][]string, limit)
-	for i := 0; i < limit; i++ {
+	rows := make([][]string, len(occurrences))
+	for i := range occurrences {
 		o := occurrences[i]
-		msg := o.Message
-		if len(msg) > 80 {
-			msg = msg[:77] + "..."
-		}
 		rows[i] = []string{
 			strconv.Itoa(o.ID),
 			output.FormatRelativeTime(o.CreatedAt),
 			o.Location,
 			o.RequestURI,
-			msg,
+			o.Message,
 		}
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(occurrences), total)
 }
diff --git a/cmd/insights.go b/cmd/insights.go
index ba4e5b7..0fc4728 100644
--- a/cmd/insights.go
+++ b/cmd/insights.go
@@ -2,7 +2,10 @@ package cmd
 
 import (
 	"fmt"
+	"sort"
+	"strings"
 
+	"github.com/scoutapm/scout/internal/api"
 	"github.com/scoutapm/scout/internal/output"
 	"github.com/spf13/cobra"
 )
@@ -55,7 +58,7 @@ func runInsightsList(cmd *cobra.Command, args []string) {
 		return
 	}
 
-	if structuredOutput(result) {
+	if structuredOutput(limitInsightCategories(result)) {
 		return
 	}
 
@@ -79,14 +82,29 @@ func runInsightsList(cmd *cobra.Command, args []string) {
 			fmt.Printf("%s %s\n", output.SuccessStyle.Render("✓"), output.DimStyle.Render(header))
 		} else {
 			fmt.Println(output.WarningStyle.Render(header))
-			for _, item := range cat.Items {
+			items, total := limitSlice(cat.Items)
+			for _, item := range items {
 				fmt.Printf("  %s %s\n", output.WarningStyle.Render("⚠"), item.Name)
 			}
+			printTruncated(len(items), total)
 		}
 		fmt.Println()
 	}
 }
 
+// limitInsightCategories applies -n to each category's items. The category
+// counts describe what exists and are left alone; -n only selects how many
+// items are listed.
+func limitInsightCategories(result *api.InsightsListResult) *api.InsightsListResult {
+	limited := *result
+	limited.Insights = make(map[string]api.InsightCategory, len(result.Insights))
+	for key, cat := range result.Insights {
+		cat.Items, _ = limitSlice(cat.Items)
+		limited.Insights[key] = cat
+	}
+	return &limited
+}
+
 func runInsightsShow(cmd *cobra.Command, args []string) {
 	client, err := getClient()
 	if err != nil {
@@ -109,7 +127,11 @@ func runInsightsShow(cmd *cobra.Command, args []string) {
 		return
 	}
 
-	if structuredOutput(result) {
+	items, total := limitSlice(result.Items)
+	limited := *result
+	limited.Items = items
+
+	if structuredOutput(&limited) {
 		return
 	}
 
@@ -117,11 +139,60 @@ func runInsightsShow(cmd *cobra.Command, args []string) {
 	fmt.Println(output.HeaderStyle.Render(header))
 	fmt.Println()
 
-	for _, item := range result.Items {
+	for _, item := range items {
 		fmt.Println(output.BoldStyle.Render(item.Name))
-		for k, v := range item.Fields {
-			fmt.Printf("  %-30s %v\n", output.DimStyle.Render(k+":"), v)
-		}
+		printInsightFields(item.Fields, "  ")
 		fmt.Println()
 	}
+	printTruncated(len(items), total)
+}
+
+// printInsightFields prints an insight's fields in key order. The API returns
+// them as a map, so without sorting the same insight prints in a different
+// order every run; nested objects are indented rather than left to Go's
+// map[...] formatting.
+func printInsightFields(fields map[string]interface{}, indent string) {
+	keys := make([]string, 0, len(fields))
+	for k := range fields {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+
+	for _, k := range keys {
+		label := output.DimStyle.Render(k + ":")
+		nested, ok := fields[k].(map[string]interface{})
+		if ok && len(nested) > 0 {
+			fmt.Printf("%s%s\n", indent, label)
+			printInsightFields(nested, indent+"  ")
+			continue
+		}
+		fmt.Printf("%s%-30s %s\n", indent, label, formatInsightValue(fields[k]))
+	}
+}
+
+// formatInsightValue renders a leaf field value for display, standing in for
+// values Go would print as <nil> or as raw syntax.
+func formatInsightValue(v interface{}) string {
+	switch tv := v.(type) {
+	case nil:
+		return "—"
+	case string:
+		if tv == "" {
+			return "—"
+		}
+		return tv
+	case []interface{}:
+		if len(tv) == 0 {
+			return "—"
+		}
+		parts := make([]string, len(tv))
+		for i, e := range tv {
+			parts[i] = formatInsightValue(e)
+		}
+		return strings.Join(parts, ", ")
+	case map[string]interface{}:
+		return "—"
+	default:
+		return fmt.Sprintf("%v", v)
+	}
 }
diff --git a/cmd/insights_test.go b/cmd/insights_test.go
new file mode 100644
index 0000000..fdc3570
--- /dev/null
+++ b/cmd/insights_test.go
@@ -0,0 +1,115 @@
+package cmd
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/scoutapm/scout/internal/api"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestFormatInsightValue(t *testing.T) {
+	tests := []struct {
+		name     string
+		value    interface{}
+		expected string
+	}{
+		{"null renders as a dash", nil, "—"},
+		{"empty string renders as a dash", "", "—"},
+		{"string", "Controller/users/index", "Controller/users/index"},
+		{"number", 42.5, "42.5"},
+		{"bool", true, "true"},
+		{"list is joined", []interface{}{"a", "b"}, "a, b"},
+		{"empty list renders as a dash", []interface{}{}, "—"},
+		{"empty map renders as a dash", map[string]interface{}{}, "—"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.expected, formatInsightValue(tt.value))
+		})
+	}
+}
+
+// Fields arrive as a Go map, which ranges in a random order.
+func TestPrintInsightFieldsIsSorted(t *testing.T) {
+	fields := map[string]interface{}{
+		"uri":               "/users",
+		"kind":              "n_plus_one",
+		"num_queries":       31.0,
+		"potential_savings": 12.5,
+		"metric_name":       "Controller/users/index",
+	}
+
+	var runs []string
+	for i := 0; i < 5; i++ {
+		runs = append(runs, captureStdout(t, func() {
+			printInsightFields(fields, "  ")
+		}))
+	}
+
+	for _, out := range runs {
+		assert.Equal(t, runs[0], out, "field order must be stable across runs")
+	}
+
+	out := runs[0]
+	for _, key := range []string{"kind", "metric_name", "num_queries", "potential_savings", "uri"} {
+		assert.Contains(t, out, key+":")
+	}
+	assert.Less(t, strings.Index(out, "kind:"), strings.Index(out, "metric_name:"))
+	assert.Less(t, strings.Index(out, "num_queries:"), strings.Index(out, "potential_savings:"))
+	assert.Less(t, strings.Index(out, "potential_savings:"), strings.Index(out, "uri:"))
+}
+
+// Nested objects used to print as Go's map[...] syntax and nulls as <nil>.
+func TestPrintInsightFieldsFormatsNestedValues(t *testing.T) {
+	out := captureStdout(t, func() {
+		printInsightFields(map[string]interface{}{
+			"uri": nil,
+			"raw_allocation_summary": map[string]interface{}{
+				"ActiveRecord": map[string]interface{}{"call_count": 79.0},
+			},
+		}, "  ")
+	})
+
+	assert.NotContains(t, out, "map[")
+	assert.NotContains(t, out, "<nil>")
+	assert.Contains(t, out, "raw_allocation_summary:")
+	assert.Contains(t, out, "ActiveRecord:")
+	assert.Contains(t, out, "call_count:")
+	assert.Contains(t, out, "uri:")
+	assert.Contains(t, out, "—")
+
+	// Nesting depth is reflected in the indentation.
+	lines := strings.Split(strings.TrimSpace(out), "\n")
+	var callCountLine string
+	for _, l := range lines {
+		if strings.Contains(l, "call_count:") {
+			callCountLine = l
+		}
+	}
+	require.NotEmpty(t, callCountLine)
+	assert.True(t, strings.HasPrefix(callCountLine, "      "), "expected nested indent, got %q", callCountLine)
+}
+
+func TestLimitInsightCategories(t *testing.T) {
+	items := []api.InsightItem{{Name: "a"}, {Name: "b"}, {Name: "c"}}
+	result := &api.InsightsListResult{
+		Insights: map[string]api.InsightCategory{
+			"n_plus_one": {Count: 3, NewCount: 1, Items: items},
+			"slow_query": {Count: 0, NewCount: 0},
+		},
+	}
+
+	withLimit(t, 2)
+	limited := limitInsightCategories(result)
+
+	assert.Len(t, limited.Insights["n_plus_one"].Items, 2)
+	assert.Empty(t, limited.Insights["slow_query"].Items)
+	// Counts describe what exists, so -n must not change them.
+	assert.Equal(t, 3, limited.Insights["n_plus_one"].Count)
+	assert.Equal(t, 1, limited.Insights["n_plus_one"].NewCount)
+	// The original result is untouched.
+	assert.Len(t, result.Insights["n_plus_one"].Items, 3)
+}
diff --git a/cmd/jobs.go b/cmd/jobs.go
index ab4f4b7..028dbaf 100644
--- a/cmd/jobs.go
+++ b/cmd/jobs.go
@@ -4,7 +4,6 @@ import (
 	"encoding/base64"
 	"fmt"
 	"strings"
-	"unicode/utf8"
 
 	"github.com/scoutapm/scout/internal/api"
 	"github.com/scoutapm/scout/internal/output"
@@ -19,7 +18,7 @@ var jobsCmd = &cobra.Command{
 	Long: `Background job performance data.
 
 Job IDs are Base64 URL-safe encodings of a job's "queue/JobName" full name.
-Get them from 'scout jobs list --json' (or --toon), or pass the full name
+Get them from 'scout jobs list --json', or pass the full name
 directly (e.g. --job default/MyWorker) and the CLI encodes it for you.
 
 Use 'scout traces list --job <job-id>' to list traces for a background job.`,
@@ -39,8 +38,13 @@ var jobsMetricsCmd = &cobra.Command{
 Valid metric types: ` + strings.Join(validJobMetricTypes, ", ") + `
 
 For execution_time, the API returns one series per category (ActiveRecord,
-Ruby, ...); the chart shows their per-timestamp total while --json/--toon
+Ruby, ...); the chart shows their per-timestamp total while --json
 output keeps the per-category breakdown.`,
+	Example: `  # By the Base64 job ID in the "job_id" field of 'scout jobs list --json'
+  scout jobs metrics --job ZGVmYXVsdC9NeVdvcmtlcg== --type execution_time --app 6
+
+  # The same job by its "queue/JobName" full name
+  scout jobs metrics --job default/MyWorker --type throughput --app 6 --from 7d`,
 	Run: runJobsMetrics,
 }
 
@@ -80,16 +84,15 @@ func runJobsList(cmd *cobra.Command, args []string) {
 		return
 	}
 
+	jobs, total := limitSlice(jobs)
+
 	if structuredOutput(jobs) {
 		return
 	}
 
-	total := len(jobs)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"Job", "Queue", "Throughput", "Exec Time", "Latency", "% Time"}
-	rows := make([][]string, limit)
-	for i := 0; i < limit; i++ {
+	rows := make([][]string, len(jobs))
+	for i := range jobs {
 		j := jobs[i]
 		rows[i] = []string{
 			j.Name,
@@ -102,7 +105,7 @@ func runJobsList(cmd *cobra.Command, args []string) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(jobs), total)
 }
 
 func runJobsMetrics(cmd *cobra.Command, args []string) {
@@ -121,12 +124,21 @@ func runJobsMetrics(cmd *cobra.Command, args []string) {
 		exitError(err.Error())
 	}
 
+	jobFlag, err := requireFlagValue("job", jobFlag)
+	if err != nil {
+		exitError(err.Error())
+	}
+
+	jobID, err := resolveJobID(jobFlag)
+	if err != nil {
+		exitError(err.Error())
+	}
+
 	from, to, err := resolveTimeframe()
 	if err != nil {
 		exitError(err.Error())
 	}
 
-	jobID := resolveJobID(jobFlag)
 	metrics, err := client.GetJobMetrics(id, jobID, jobMetricTypeFlag, from, to)
 	if err != nil {
 		handleAPIError(err)
@@ -159,30 +171,18 @@ func chartSeries(metricType string, m *api.JobMetricsResult) []api.MetricPoint {
 // resolveJobID accepts either an already-encoded job ID or a "queue/JobName"
 // full name and returns the Base64 URL-safe job ID the API expects (matching
 // Ruby's Base64.urlsafe_encode64, including padding).
-func resolveJobID(s string) string {
+//
+// A value that is neither form — most often a job class name copy-pasted
+// without its queue — is rejected here rather than passed through to the
+// server, which answers an unrecognized id with a bare 500.
+func resolveJobID(s string) (string, error) {
 	if strings.Contains(s, "/") {
-		return base64.URLEncoding.EncodeToString([]byte(s))
-	}
-	return s
-}
-
-// decodeJobID decodes a Base64 URL-safe job ID back to its "queue/JobName"
-// full name. Returns false if the value is not a decodable job ID.
-func decodeJobID(id string) (string, bool) {
-	if id == "" {
-		return "", false
-	}
-	b, err := base64.URLEncoding.DecodeString(id)
-	if err != nil {
-		b, err = base64.RawURLEncoding.DecodeString(id)
-		if err != nil {
-			return "", false
-		}
+		return base64.URLEncoding.EncodeToString([]byte(s)), nil
 	}
-	if len(b) == 0 || !utf8.Valid(b) {
-		return "", false
+	if name, ok := decodeBase64ID(s); !ok || !strings.Contains(name, "/") {
+		return "", fmt.Errorf("invalid job %q — expected a job id from 'scout jobs list --json' (the job_id field), or a full name like default/MyWorker", s)
 	}
-	return string(b), true
+	return s, nil
 }
 
 // jobDisplayName returns a human-friendly job name for titles: the full name
@@ -191,7 +191,7 @@ func jobDisplayName(s string) string {
 	if strings.Contains(s, "/") {
 		return s
 	}
-	if name, ok := decodeJobID(s); ok {
+	if name, ok := decodeBase64ID(s); ok {
 		return name
 	}
 	return s
diff --git a/cmd/jobs_test.go b/cmd/jobs_test.go
index 04ffb29..f627135 100644
--- a/cmd/jobs_test.go
+++ b/cmd/jobs_test.go
@@ -5,6 +5,7 @@ import (
 
 	"github.com/scoutapm/scout/internal/api"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 const (
@@ -22,37 +23,51 @@ func TestResolveJobID(t *testing.T) {
 		{"encoded id passes through", testJobID, testJobID},
 		{"full name needing padding", "default/ReportJob", "ZGVmYXVsdC9SZXBvcnRKb2I="},
 		{"Job/ prefixed full name is encoded", "Job/default/MyWorker", "Sm9iL2RlZmF1bHQvTXlXb3JrZXI="},
-		{"empty passes through", "", ""},
+		{"unpadded id passes through", "ZGVmYXVsdC9SZXBvcnRKb2I", "ZGVmYXVsdC9SZXBvcnRKb2I"},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			assert.Equal(t, tt.expected, resolveJobID(tt.input))
+			got, err := resolveJobID(tt.input)
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, got)
 		})
 	}
 }
 
-func TestDecodeJobID(t *testing.T) {
-	name, ok := decodeJobID(testJobID)
+func TestResolveJobIDRejectsMalformed(t *testing.T) {
+	// A job class name copy-pasted without its queue, a value that isn't
+	// base64 at all, and base64 that doesn't decode to a "queue/JobName".
+	for _, input := range []string{"MyWorker", "SomeWorkerName", "not base64!!", "", "YWJj"} {
+		_, err := resolveJobID(input)
+		require.Error(t, err, input)
+		assert.Contains(t, err.Error(), "default/MyWorker", input)
+	}
+}
+
+func TestDecodeBase64ID(t *testing.T) {
+	name, ok := decodeBase64ID(testJobID)
 	assert.True(t, ok)
 	assert.Equal(t, testJobFullName, name)
 
 	// Round trip
-	assert.Equal(t, testJobID, resolveJobID(name))
+	encoded, err := resolveJobID(name)
+	require.NoError(t, err)
+	assert.Equal(t, testJobID, encoded)
 
 	// Padded id
-	name, ok = decodeJobID("ZGVmYXVsdC9SZXBvcnRKb2I=")
+	name, ok = decodeBase64ID("ZGVmYXVsdC9SZXBvcnRKb2I=")
 	assert.True(t, ok)
 	assert.Equal(t, "default/ReportJob", name)
 
 	// Unpadded id is tolerated
-	name, ok = decodeJobID("ZGVmYXVsdC9SZXBvcnRKb2I")
+	name, ok = decodeBase64ID("ZGVmYXVsdC9SZXBvcnRKb2I")
 	assert.True(t, ok)
 	assert.Equal(t, "default/ReportJob", name)
 
-	_, ok = decodeJobID("")
+	_, ok = decodeBase64ID("")
 	assert.False(t, ok)
 
-	_, ok = decodeJobID("not base64!!")
+	_, ok = decodeBase64ID("not base64!!")
 	assert.False(t, ok)
 }
 
diff --git a/cmd/metrics.go b/cmd/metrics.go
index 3cabe67..c824a5c 100644
--- a/cmd/metrics.go
+++ b/cmd/metrics.go
@@ -2,11 +2,16 @@ package cmd
 
 import (
 	"fmt"
+	"slices"
+	"strings"
 
+	"github.com/scoutapm/scout/internal/api"
 	"github.com/scoutapm/scout/internal/output"
 	"github.com/spf13/cobra"
 )
 
+var validMetricTypes = []string{"apdex", "response_time", "response_time_95th", "errors", "throughput", "queue_time"}
+
 var metricsCmd = &cobra.Command{
 	Use:   "metrics",
 	Short: "Application metrics",
@@ -15,19 +20,23 @@ var metricsCmd = &cobra.Command{
 var metricsGetCmd = &cobra.Command{
 	Use:   "get",
 	Short: "Get metric data with ASCII chart",
-	Run:   runMetricsGet,
+	Example: `  scout metrics get --type response_time --app 6
+  scout metrics get --type throughput --app 6 --from 7d`,
+	Run: runMetricsGet,
 }
 
 var metricTypeFlag string
 
 func init() {
-	metricsGetCmd.Flags().StringVar(&metricTypeFlag, "type", "", "Metric type (apdex, response_time, response_time_95th, errors, throughput, queue_time)")
+	metricsGetCmd.Flags().StringVar(&metricTypeFlag, "type", "", "Metric type ("+strings.Join(validMetricTypes, ", ")+")")
 	_ = metricsGetCmd.MarkFlagRequired("type")
 	metricsCmd.AddCommand(metricsGetCmd)
 	rootCmd.AddCommand(metricsCmd)
 }
 
 func runMetricsGet(cmd *cobra.Command, args []string) {
+	requireValidMetricType(metricTypeFlag)
+
 	client, err := getClient()
 	if err != nil {
 		exitError(err.Error())
@@ -57,11 +66,33 @@ func runMetricsGet(cmd *cobra.Command, args []string) {
 	summary := metrics.Summaries[metricTypeFlag]
 
 	unit := unitForMetricType(metricTypeFlag)
-	title := fmt.Sprintf("%s — App #%d", metricTypeFlag, id)
+	title := fmt.Sprintf("%s — %s", metricTypeFlag, appDisplayName(client, id))
 
 	fmt.Println(output.RenderChart(title, series, summary, unit))
 }
 
+func isValidMetricType(t string) bool {
+	return slices.Contains(validMetricTypes, t)
+}
+
+// requireValidMetricType exits with the valid list rather than round-tripping
+// to the server for a 422.
+func requireValidMetricType(t string) {
+	if !isValidMetricType(t) {
+		exitError(fmt.Sprintf("invalid metric type %q — valid types: %s",
+			t, strings.Join(validMetricTypes, ", ")))
+	}
+}
+
+// appDisplayName returns the app's name for a chart title, falling back to
+// "App #<id>" when the name can't be fetched.
+func appDisplayName(client *api.Client, id int) string {
+	if app, err := client.GetApp(id); err == nil && app.Name != "" {
+		return app.Name
+	}
+	return fmt.Sprintf("App #%d", id)
+}
+
 func unitForMetricType(t string) string {
 	switch t {
 	case "response_time", "response_time_95th", "queue_time":
diff --git a/cmd/metrics_test.go b/cmd/metrics_test.go
new file mode 100644
index 0000000..fa72c0e
--- /dev/null
+++ b/cmd/metrics_test.go
@@ -0,0 +1,43 @@
+package cmd
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestIsValidMetricType(t *testing.T) {
+	for _, valid := range validMetricTypes {
+		assert.True(t, isValidMetricType(valid), valid)
+	}
+	assert.False(t, isValidMetricType("memory"))
+	assert.False(t, isValidMetricType("Response_Time"))
+	assert.False(t, isValidMetricType(""))
+}
+
+func TestUnitForMetricType(t *testing.T) {
+	assert.Equal(t, "ms", unitForMetricType("response_time"))
+	assert.Equal(t, "ms", unitForMetricType("queue_time"))
+	assert.Equal(t, " rpm", unitForMetricType("throughput"))
+	assert.Equal(t, "", unitForMetricType("apdex"))
+}
+
+func TestEndpointDisplayName(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{name: "base64 id decodes", input: "YXBpL21ldHJpY3Mvc2hvdw==", want: "api/metrics/show"},
+		{name: "unpadded base64 id decodes", input: "YXBpL21ldHJpY3Mvc2hvdw", want: "api/metrics/show"},
+		{name: "plain name passes through", input: "api/metrics/show", want: "api/metrics/show"},
+		{name: "empty passes through", input: "", want: ""},
+		{name: "non-printable decode passes through", input: "AAAA", want: "AAAA"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, endpointDisplayName(tt.input))
+		})
+	}
+}
diff --git a/cmd/root.go b/cmd/root.go
index 8b70ba8..f9f8ab5 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -1,11 +1,12 @@
 package cmd
 
 import (
+	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"os"
-
-	toon "github.com/toon-format/toon-go"
+	"strings"
+	"unicode/utf8"
 
 	"github.com/scoutapm/scout/internal/api"
 	"github.com/scoutapm/scout/internal/config"
@@ -20,7 +21,6 @@ var (
 	Version = "dev"
 
 	jsonOutput bool
-	toonOutput bool
 	appID      int
 	fromFlag   string
 	toFlag     string
@@ -29,14 +29,15 @@ var (
 )
 
 var rootCmd = &cobra.Command{
-	Use:     "scout",
-	Short:   "Scout APM CLI — monitor application performance from the terminal",
-	Long:    "A command-line interface for Scout APM. View apps, metrics, endpoints, background jobs, traces, errors, and insights.\n\nWhen piped, output defaults to TOON format (token-efficient for LLMs). Use --json for raw JSON or --toon to force TOON in a terminal.",
+	Use:   "scout",
+	Short: "Scout APM CLI — monitor application performance from the terminal",
+	Long: "A command-line interface for Scout APM. View apps, metrics, endpoints, background jobs, traces, errors, anomalies, insights, usage, and billing.\n\n" +
+		"When piped, output defaults to JSON. Use --json to force JSON in a terminal.",
 	Version: Version,
 	PersistentPreRun: func(cmd *cobra.Command, args []string) {
-		// Auto-enable TOON when piped (unless --json was explicitly set)
-		if !jsonOutput && !toonOutput && !term.IsTerminal(int(os.Stdout.Fd())) {
-			toonOutput = true
+		// Auto-enable JSON when piped, so scripts and agents get structured output.
+		if !jsonOutput && !term.IsTerminal(int(os.Stdout.Fd())) {
+			jsonOutput = true
 		}
 		if noColor {
 			_ = os.Setenv("NO_COLOR", "1")
@@ -51,10 +52,9 @@ func Execute() {
 }
 
 func init() {
-	rootCmd.PersistentFlags().BoolVar(&jsonOutput, "json", false, "Output raw JSON")
-	rootCmd.PersistentFlags().BoolVar(&toonOutput, "toon", false, "Output in TOON format (token-efficient, auto-enabled when piped)")
+	rootCmd.PersistentFlags().BoolVar(&jsonOutput, "json", false, "Output raw JSON (auto-enabled when piped)")
 	rootCmd.PersistentFlags().IntVar(&appID, "app", 0, "Application ID")
-	rootCmd.PersistentFlags().StringVar(&fromFlag, "from", "", "Start time (relative: 1h, 7d, 30m or ISO 8601)")
+	rootCmd.PersistentFlags().StringVar(&fromFlag, "from", "", "Start time (relative: 30m, 1h, 7d, 2w or ISO 8601)")
 	rootCmd.PersistentFlags().StringVar(&toFlag, "to", "", "End time (relative or ISO 8601, default: now)")
 	rootCmd.PersistentFlags().BoolVar(&noColor, "no-color", false, "Disable colors")
 	rootCmd.PersistentFlags().IntVarP(&limitFlag, "limit", "n", 0, "Max number of results to show (0 = no limit)")
@@ -69,6 +69,9 @@ func getClient() (*api.Client, error) {
 }
 
 func requireAppID() (int, error) {
+	if err := validateAppIDFlag(appID, appIDFlagPassed()); err != nil {
+		return 0, err
+	}
 	if appID > 0 {
 		return appID, nil
 	}
@@ -82,6 +85,63 @@ func requireAppID() (int, error) {
 	return 0, fmt.Errorf("no app specified — use --app flag or set default_app_id in config")
 }
 
+// appIDFilter returns the app id for commands that treat --app as an optional
+// filter rather than a requirement. Returns 0 when --app was not passed.
+func appIDFilter() (int, error) {
+	passed := appIDFlagPassed()
+	if err := validateAppIDFlag(appID, passed); err != nil {
+		return 0, err
+	}
+	if !passed {
+		return 0, nil
+	}
+	return appID, nil
+}
+
+func appIDFlagPassed() bool {
+	return rootCmd.PersistentFlags().Changed("app")
+}
+
+// validateAppIDFlag rejects a --app that was passed with a value that can
+// never be an app id, so it isn't mistaken for the flag being absent.
+func validateAppIDFlag(value int, passed bool) error {
+	if passed && value <= 0 {
+		return fmt.Errorf("invalid --app value: %d — app ids are positive integers", value)
+	}
+	return nil
+}
+
+// decodeBase64ID decodes a Base64 URL-safe id (as used for endpoint and job
+// ids, matching Ruby's Base64.urlsafe_encode64) back to the name it encodes.
+// Returns false if the value is not a decodable id.
+func decodeBase64ID(id string) (string, bool) {
+	if id == "" {
+		return "", false
+	}
+	b, err := base64.URLEncoding.DecodeString(id)
+	if err != nil {
+		b, err = base64.RawURLEncoding.DecodeString(id)
+		if err != nil {
+			return "", false
+		}
+	}
+	if len(b) == 0 || !utf8.Valid(b) {
+		return "", false
+	}
+	return string(b), true
+}
+
+// requireFlagValue rejects a blank value for a flag that needs one. Cobra's
+// required-flag check is satisfied by an empty string, which would otherwise
+// reach the server and come back as an opaque error.
+func requireFlagValue(name, value string) (string, error) {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return "", fmt.Errorf("--%s requires a value", name)
+	}
+	return trimmed, nil
+}
+
 func resolveTimeframe() (string, string, error) {
 	return timeutil.ResolveTimeframe(fromFlag, toFlag)
 }
@@ -92,35 +152,26 @@ func outputJSON(data interface{}) {
 	_ = enc.Encode(map[string]interface{}{"data": data})
 }
 
-func outputTOON(data interface{}) {
-	out, err := toon.MarshalString(data)
-	if err != nil {
-		// Fall back to JSON if TOON encoding fails
-		outputJSON(data)
-		return
-	}
-	fmt.Print(out)
-}
-
-// structuredOutput returns true and outputs the data if --json or --toon
-// (or piped) is active. Returns false if human-readable output should be used.
+// structuredOutput returns true and outputs the data if --json (or piped) is
+// active. Returns false if human-readable output should be used.
 func structuredOutput(data interface{}) bool {
 	if jsonOutput {
 		outputJSON(data)
 		return true
 	}
-	if toonOutput {
-		outputTOON(data)
-		return true
-	}
 	return false
 }
 
-func applyLimit(total int) (limit int, truncated bool) {
+// limitSlice applies -n/--limit to a list of results, returning the rows to
+// show and the total before limiting. Callers limit before handing results to
+// structuredOutput so -n applies to --json output too, and report the
+// untruncated total via printTruncated.
+func limitSlice[T any](items []T) (shown []T, total int) {
+	total = len(items)
 	if limitFlag > 0 && limitFlag < total {
-		return limitFlag, true
+		return items[:limitFlag], total
 	}
-	return total, false
+	return items, total
 }
 
 func printTruncated(shown, total int) {
diff --git a/cmd/root_test.go b/cmd/root_test.go
new file mode 100644
index 0000000..3a96b9b
--- /dev/null
+++ b/cmd/root_test.go
@@ -0,0 +1,114 @@
+package cmd
+
+import (
+	"encoding/json"
+	"io"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// withLimit sets -n for the duration of a test.
+func withLimit(t *testing.T, n int) {
+	t.Helper()
+	prev := limitFlag
+	limitFlag = n
+	t.Cleanup(func() { limitFlag = prev })
+}
+
+// captureStdout runs fn with os.Stdout redirected and returns what it wrote.
+func captureStdout(t *testing.T, fn func()) string {
+	t.Helper()
+	r, w, err := os.Pipe()
+	require.NoError(t, err)
+
+	prev := os.Stdout
+	os.Stdout = w
+	defer func() { os.Stdout = prev }()
+
+	fn()
+	require.NoError(t, w.Close())
+
+	out, err := io.ReadAll(r)
+	require.NoError(t, err)
+	return string(out)
+}
+
+func TestLimitSlice(t *testing.T) {
+	items := []int{1, 2, 3, 4, 5}
+
+	tests := []struct {
+		name  string
+		limit int
+		shown []int
+	}{
+		{"no limit", 0, items},
+		{"limit below total", 2, []int{1, 2}},
+		{"limit equal to total", 5, items},
+		{"limit above total", 99, items},
+		{"negative limit ignored", -1, items},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			withLimit(t, tt.limit)
+			shown, total := limitSlice(items)
+			assert.Equal(t, tt.shown, shown)
+			assert.Equal(t, 5, total, "total is the count before limiting")
+		})
+	}
+}
+
+func TestLimitSliceEmpty(t *testing.T) {
+	withLimit(t, 3)
+	shown, total := limitSlice([]string{})
+	assert.Empty(t, shown)
+	assert.Equal(t, 0, total)
+}
+
+// -n used to apply only to the human table, leaving --json unlimited.
+func TestStructuredOutputHonorsLimit(t *testing.T) {
+	withLimit(t, 2)
+	prevJSON := jsonOutput
+	jsonOutput = true
+	t.Cleanup(func() { jsonOutput = prevJSON })
+
+	out := captureStdout(t, func() {
+		shown, _ := limitSlice([]int{1, 2, 3, 4, 5})
+		assert.True(t, structuredOutput(shown))
+	})
+
+	var decoded struct {
+		Data []int `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal([]byte(out), &decoded))
+	assert.Equal(t, []int{1, 2}, decoded.Data)
+}
+
+func TestValidateAppIDFlag(t *testing.T) {
+	// Not passed: the default 0 means "use the configured default".
+	assert.NoError(t, validateAppIDFlag(0, false))
+	assert.NoError(t, validateAppIDFlag(6, true))
+
+	err := validateAppIDFlag(0, true)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid --app value: 0")
+
+	err = validateAppIDFlag(-5, true)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid --app value: -5")
+}
+
+func TestRequireFlagValue(t *testing.T) {
+	got, err := requireFlagValue("endpoint", "  abc  ")
+	require.NoError(t, err)
+	assert.Equal(t, "abc", got)
+
+	for _, blank := range []string{"", "   ", "\t\n"} {
+		_, err := requireFlagValue("job", blank)
+		require.Error(t, err)
+		assert.Equal(t, "--job requires a value", err.Error())
+	}
+}
diff --git a/cmd/setup.go b/cmd/setup.go
index 8c6f37a..a903582 100644
--- a/cmd/setup.go
+++ b/cmd/setup.go
@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/scoutapm/scout/internal/output"
 	"github.com/spf13/cobra"
@@ -39,13 +40,15 @@ func init() {
 	rootCmd.AddCommand(setupCmd)
 }
 
-func frameworkDocsURL(name string) (string, bool) {
+// lookupFramework resolves a framework name case-insensitively, returning its
+// canonical name and docs URL.
+func lookupFramework(name string) (canonicalName, docsURL string, ok bool) {
 	for _, f := range frameworks {
-		if f.name == name {
-			return f.docsURL, true
+		if strings.EqualFold(f.name, name) {
+			return f.name, f.docsURL, true
 		}
 	}
-	return "", false
+	return "", "", false
 }
 
 func runSetup(cmd *cobra.Command, args []string) {
@@ -71,10 +74,9 @@ func runSetup(cmd *cobra.Command, args []string) {
 		return
 	}
 
-	framework := args[0]
-	docsURL, found := frameworkDocsURL(framework)
-	if !found {
-		exitError(fmt.Sprintf("unknown framework: %s", framework))
+	framework, docsURL, ok := lookupFramework(args[0])
+	if !ok {
+		exitError(fmt.Sprintf("unknown framework %q — run 'scout setup' with no arguments to list the supported names", args[0]))
 	}
 
 	if structuredOutput(map[string]interface{}{
diff --git a/cmd/setup_test.go b/cmd/setup_test.go
index ad0843b..32aa7a4 100644
--- a/cmd/setup_test.go
+++ b/cmd/setup_test.go
@@ -31,29 +31,37 @@ func TestFrameworkTableIsWellFormed(t *testing.T) {
 	}
 }
 
-func TestFrameworkDocsURLLookup(t *testing.T) {
+func TestLookupFramework(t *testing.T) {
 	tests := []struct {
-		name string
-		want string
+		input   string
+		want    string
+		wantURL string
+		found   bool
 	}{
-		{"rails", "https://scoutapm.com/docs/ruby"},
-		{"django", "https://scoutapm.com/docs/python/django"},
-		{"sinatra", "https://scoutapm.com/docs/ruby/sinatra"},
-		{"express", "https://scoutapm.com/docs/node/express"},
-		{"sidekiq", "https://scoutapm.com/docs/ruby#instrumented-libraries"},
+		{input: "rails", want: "rails", wantURL: "https://scoutapm.com/docs/ruby", found: true},
+		{input: "Rails", want: "rails", wantURL: "https://scoutapm.com/docs/ruby", found: true},
+		{input: "RAILS", want: "rails", wantURL: "https://scoutapm.com/docs/ruby", found: true},
+		{input: "FastAPI", want: "fastapi", wantURL: "https://scoutapm.com/docs/python/fastapi", found: true},
+		{input: "django", want: "django", wantURL: "https://scoutapm.com/docs/python/django", found: true},
+		{input: "sinatra", want: "sinatra", wantURL: "https://scoutapm.com/docs/ruby/sinatra", found: true},
+		{input: "express", want: "express", wantURL: "https://scoutapm.com/docs/node/express", found: true},
+		{input: "sidekiq", want: "sidekiq", wantURL: "https://scoutapm.com/docs/ruby#instrumented-libraries", found: true},
+		{input: "ruby", found: false},
+		{input: "cobol", found: false},
+		{input: "", found: false},
 	}
 
 	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got, found := frameworkDocsURL(tt.name)
-			require.True(t, found)
-			assert.Equal(t, tt.want, got)
+		t.Run(tt.input, func(t *testing.T) {
+			name, docsURL, ok := lookupFramework(tt.input)
+			assert.Equal(t, tt.found, ok)
+			if tt.found {
+				assert.Equal(t, tt.want, name)
+				assert.Equal(t, tt.wantURL, docsURL)
+			} else {
+				assert.Empty(t, name)
+				assert.Empty(t, docsURL)
+			}
 		})
 	}
 }
-
-func TestFrameworkDocsURLUnknown(t *testing.T) {
-	got, found := frameworkDocsURL("cobol")
-	assert.False(t, found)
-	assert.Empty(t, got)
-}
diff --git a/cmd/traces.go b/cmd/traces.go
index cdfaeb2..fe74cab 100644
--- a/cmd/traces.go
+++ b/cmd/traces.go
@@ -21,6 +21,16 @@ var tracesListCmd = &cobra.Command{
 
 Exactly one of --endpoint or --job is required. Traces are the slowest
 recorded within the timeframe (max 100, within the last 7 days).`,
+	Example: `  # Traces for an endpoint, by the Base64 endpoint ID in the
+  # "link" field of 'scout endpoints list --json'
+  scout traces list --endpoint YXBpL21ldHJpY3Mvc2hvdw== --app 6
+
+  # Traces for a background job, by the "job_id" field of
+  # 'scout jobs list --json'
+  scout traces list --job ZGVmYXVsdC9NeVdvcmtlcg== --app 6
+
+  # The same job by its "queue/JobName" full name
+  scout traces list --job default/MyWorker --app 6 --from 7d`,
 	Run: runTracesList,
 }
 
@@ -60,32 +70,44 @@ func runTracesList(cmd *cobra.Command, args []string) {
 		exitError(err.Error())
 	}
 
-	from, to, err := resolveTimeframe()
+	if cmd.Flags().Changed("job") {
+		jobID, err := resolveTracesJobID()
+		if err != nil {
+			exitError(err.Error())
+		}
+		from, to, err := resolveTimeframe()
+		if err != nil {
+			exitError(err.Error())
+		}
+		runJobTracesList(client, id, jobID, from, to)
+		return
+	}
+
+	endpoint, err := requireFlagValue("endpoint", tracesEndpointFlag)
 	if err != nil {
 		exitError(err.Error())
 	}
 
-	if tracesJobFlag != "" {
-		runJobTracesList(client, id, from, to)
-		return
+	from, to, err := resolveTimeframe()
+	if err != nil {
+		exitError(err.Error())
 	}
 
-	traces, err := client.ListTraces(id, tracesEndpointFlag, from, to)
+	traces, err := client.ListTraces(id, endpoint, from, to)
 	if err != nil {
 		handleAPIError(err)
 		return
 	}
 
+	traces, total := limitSlice(traces)
+
 	if structuredOutput(traces) {
 		return
 	}
 
-	total := len(traces)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"ID", "Time", "Duration", "Memory", "Endpoint", "URI"}
-	rows := make([][]string, limit)
-	for i := 0; i < limit; i++ {
+	rows := make([][]string, len(traces))
+	for i := range traces {
 		t := traces[i]
 		rows[i] = []string{
 			strconv.Itoa(t.ID),
@@ -98,26 +120,34 @@ func runTracesList(cmd *cobra.Command, args []string) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(traces), total)
+}
+
+// resolveTracesJobID validates --job and returns the encoded job id.
+func resolveTracesJobID() (string, error) {
+	job, err := requireFlagValue("job", tracesJobFlag)
+	if err != nil {
+		return "", err
+	}
+	return resolveJobID(job)
 }
 
-func runJobTracesList(client *api.Client, id int, from, to string) {
-	traces, err := client.ListJobTraces(id, resolveJobID(tracesJobFlag), from, to)
+func runJobTracesList(client *api.Client, id int, jobID, from, to string) {
+	traces, err := client.ListJobTraces(id, jobID, from, to)
 	if err != nil {
 		handleAPIError(err)
 		return
 	}
 
+	traces, total := limitSlice(traces)
+
 	if structuredOutput(traces) {
 		return
 	}
 
-	total := len(traces)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"ID", "Time", "Duration", "Job", "Queue"}
-	rows := make([][]string, limit)
-	for i := 0; i < limit; i++ {
+	rows := make([][]string, len(traces))
+	for i := range traces {
 		t := traces[i]
 		rows[i] = []string{
 			strconv.Itoa(t.ID),
@@ -129,7 +159,7 @@ func runJobTracesList(client *api.Client, id int, from, to string) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(traces), total)
 }
 
 func runTracesShow(cmd *cobra.Command, args []string) {
@@ -150,7 +180,7 @@ func runTracesShow(cmd *cobra.Command, args []string) {
 
 	trace, err := client.GetTrace(id, traceID)
 	if err != nil {
-		handleAPIError(err)
+		handleAPIError(traceShowError(err))
 		return
 	}
 
@@ -160,3 +190,18 @@ func runTracesShow(cmd *cobra.Command, args []string) {
 
 	fmt.Println(output.RenderSpanTree(trace))
 }
+
+// traceShowError explains a 404 from 'traces show'. Job trace ids look exactly
+// like endpoint trace ids in 'traces list --job' output, and the API has no
+// detail endpoint for them, so the bare "not found" is misleading.
+func traceShowError(err error) error {
+	apiErr, ok := err.(*api.APIError)
+	if !ok || apiErr.StatusCode != 404 {
+		return err
+	}
+	return &api.APIError{
+		StatusCode: apiErr.StatusCode,
+		Message: apiErr.Message +
+			" — note: background job traces have no detail endpoint; only endpoint (web request) traces can be shown in full",
+	}
+}
diff --git a/cmd/traces_test.go b/cmd/traces_test.go
new file mode 100644
index 0000000..102bf9e
--- /dev/null
+++ b/cmd/traces_test.go
@@ -0,0 +1,27 @@
+package cmd
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/scoutapm/scout/internal/api"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestTraceShowError(t *testing.T) {
+	// A 404 is most often a job trace id, which has no detail endpoint.
+	err := traceShowError(&api.APIError{StatusCode: 404, Message: "Record Not Found"})
+	var apiErr *api.APIError
+	require.True(t, errors.As(err, &apiErr))
+	assert.Equal(t, 404, apiErr.StatusCode)
+	assert.Contains(t, apiErr.Message, "Record Not Found")
+	assert.Contains(t, apiErr.Message, "background job traces")
+
+	// Other statuses pass through untouched.
+	original := &api.APIError{StatusCode: 500, Message: "Internal Server Error"}
+	assert.Same(t, original, traceShowError(original))
+
+	plain := errors.New("connection refused")
+	assert.Same(t, plain, traceShowError(plain))
+}
diff --git a/cmd/usage.go b/cmd/usage.go
index c250e1d..f378dcf 100644
--- a/cmd/usage.go
+++ b/cmd/usage.go
@@ -87,6 +87,11 @@ func runUsage(cmd *cobra.Command, args []string) {
 		exitError(err.Error())
 	}
 
+	filterID, err := appIDFilter()
+	if err != nil {
+		exitError(err.Error())
+	}
+
 	tf, err := resolveUsageTimeframe(client)
 	if err != nil {
 		exitError(err.Error())
@@ -98,10 +103,14 @@ func runUsage(cmd *cobra.Command, args []string) {
 		handleAPIError(err)
 		return
 	}
+	apps, err = filterApps(apps, filterID)
+	if err != nil {
+		exitError(err.Error())
+	}
 
 	chunks := splitTimeframe(from, to)
 
-	results := output.RunWithProgress("Fetching usage data", !jsonOutput && !toonOutput, func(update func(float64)) []appUsage {
+	results := output.RunWithProgress("Fetching usage data", !jsonOutput, func(update func(float64)) []appUsage {
 		return fetchAllApps(apps, func(a api.App) appUsage {
 			return appUsage{
 				ID:           a.ID,
@@ -127,23 +136,24 @@ func runUsage(cmd *cobra.Command, args []string) {
 		return results[i].Transactions > results[j].Transactions
 	})
 
-	if structuredOutput(results) {
-		return
-	}
-
-	printUsageHeader(tf)
-
+	// The grand total covers every app in the timeframe; -n only selects how
+	// many rows are shown.
 	var grandTotal float64
 	for _, r := range results {
 		grandTotal += r.Transactions
 	}
 
-	total := len(results)
-	limit, _ := applyLimit(total)
+	results, total := limitSlice(results)
+
+	if usageStructuredOutput(tf, results) {
+		return
+	}
+
+	printUsageHeader(tf)
 
 	headers := []string{"Name", "Web Transactions", "% of Web"}
-	rows := make([][]string, limit)
-	for i := 0; i < limit; i++ {
+	rows := make([][]string, len(results))
+	for i := range results {
 		r := results[i]
 		pct := 0.0
 		if grandTotal > 0 {
@@ -157,24 +167,42 @@ func runUsage(cmd *cobra.Command, args []string) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(results), total)
 	printTotalFooter(grandTotal)
 	printServerTotal(tf)
 }
 
+// filterApps narrows the app list to a single app when --app was given.
+func filterApps(apps []api.App, filterID int) ([]api.App, error) {
+	if filterID <= 0 {
+		return apps, nil
+	}
+	for _, a := range apps {
+		if a.ID == filterID {
+			return []api.App{a}, nil
+		}
+	}
+	return nil, fmt.Errorf("app %d not found in this account", filterID)
+}
+
 func runUsageByDay(cmd *cobra.Command, args []string) {
 	client, err := getClient()
 	if err != nil {
 		exitError(err.Error())
 	}
 
+	filterID, err := appIDFilter()
+	if err != nil {
+		exitError(err.Error())
+	}
+
 	tf, err := resolveUsageTimeframe(client)
 	if err != nil {
 		exitError(err.Error())
 	}
 
-	if appID > 0 {
-		runUsageByDaySingleApp(client, appID, tf)
+	if filterID > 0 {
+		runUsageByDaySingleApp(client, filterID, tf)
 	} else if byApp {
 		runUsageByDayByApp(client, tf)
 	} else {
@@ -192,26 +220,25 @@ func runUsageByDayAllApps(client *api.Client, tf usageTimeframe) {
 
 	chunks := splitTimeframe(from, to)
 
-	allPoints := output.RunWithProgress("Fetching daily usage data", !jsonOutput && !toonOutput, func(update func(float64)) []api.MetricPoint {
+	allPoints := output.RunWithProgress("Fetching daily usage data", !jsonOutput, func(update func(float64)) []api.MetricPoint {
 		return fetchAllAppPoints(client, apps, chunks, func(done, total int) {
 			update(float64(done) / float64(total))
 		})
 	})
 	days := bucketByDay(allPoints)
 
-	if structuredOutput(days) {
+	days, total := limitSlice(days)
+
+	if usageStructuredOutput(tf, days) {
 		return
 	}
 
 	printUsageHeader(tf)
 
-	total := len(days)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"Day", "Web Transactions"}
-	rows := make([][]string, limit)
+	rows := make([][]string, len(days))
 	var grandTotal int64
-	for i := 0; i < limit; i++ {
+	for i := range days {
 		d := days[i]
 		grandTotal += d.Transactions
 		rows[i] = []string{
@@ -221,7 +248,7 @@ func runUsageByDayAllApps(client *api.Client, tf usageTimeframe) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(days), total)
 	printTotalFooter(float64(grandTotal))
 	printServerTotal(tf)
 }
@@ -235,7 +262,7 @@ func runUsageByDayByApp(client *api.Client, tf usageTimeframe) {
 	}
 
 	chunks := splitTimeframe(from, to)
-	showProgress := !jsonOutput && !toonOutput
+	showProgress := !jsonOutput
 
 	type appPointsResult struct {
 		app    api.App
@@ -368,17 +395,21 @@ func runUsageByDayByApp(client *api.Client, tf usageTimeframe) {
 		})
 	}
 
-	if structuredOutput(reports) {
-		return
-	}
-
-	printUsageHeader(tf)
-
+	// The grand total covers every day in the timeframe; -n only selects how
+	// many days are shown.
 	var grandTotal int64
 	for _, report := range reports {
 		grandTotal += report.Total
 	}
 
+	reports, total := limitSlice(reports)
+
+	if usageStructuredOutput(tf, reports) {
+		return
+	}
+
+	printUsageHeader(tf)
+
 	headers := []string{"Day", "App", "Web Transactions", "% of Day", "% of Web", "Top Endpoint"}
 	var rows [][]string
 	for i, report := range reports {
@@ -405,6 +436,7 @@ func runUsageByDayByApp(client *api.Client, tf usageTimeframe) {
 		}
 	}
 	fmt.Println(output.RenderTable(headers, rows))
+	printTruncated(len(reports), total)
 
 	if grandTotal > 0 {
 		fmt.Printf("Total: %s web transactions\n", formatTransactions(float64(grandTotal)))
@@ -415,7 +447,7 @@ func runUsageByDayByApp(client *api.Client, tf usageTimeframe) {
 func runUsageByDaySingleApp(client *api.Client, id int, tf usageTimeframe) {
 	from, to := tf.from, tf.to
 	chunks := splitTimeframe(from, to)
-	showProgress := !jsonOutput && !toonOutput
+	showProgress := !jsonOutput
 
 	days := output.RunWithProgress("Fetching usage data", showProgress, func(update func(float64)) []dailyUsage {
 		points := fetchAppPoints(client, id, chunks)
@@ -452,19 +484,18 @@ func runUsageByDaySingleApp(client *api.Client, id int, tf usageTimeframe) {
 		return days
 	})
 
-	if structuredOutput(days) {
+	days, total := limitSlice(days)
+
+	if usageStructuredOutput(tf, days) {
 		return
 	}
 
 	printUsageHeader(tf)
 
-	total := len(days)
-	limit, _ := applyLimit(total)
-
 	headers := []string{"Day", "Web Transactions", "Top Endpoint"}
-	rows := make([][]string, limit)
+	rows := make([][]string, len(days))
 	var grandTotal int64
-	for i := 0; i < limit; i++ {
+	for i := range days {
 		d := days[i]
 		grandTotal += d.Transactions
 		rows[i] = []string{
@@ -475,7 +506,7 @@ func runUsageByDaySingleApp(client *api.Client, id int, tf usageTimeframe) {
 	}
 
 	fmt.Println(output.RenderTable(headers, rows))
-	printTruncated(limit, total)
+	printTruncated(len(days), total)
 	printTotalFooter(float64(grandTotal))
 	printServerTotal(tf)
 }
@@ -531,6 +562,39 @@ func resolveUsageTimeframe(client *api.Client) (usageTimeframe, error) {
 	}, nil
 }
 
+// billingUsage wraps a usage result with the period it covers and the
+// server-reported figure for that period, so --billing-period --json output
+// says which window it describes and what the billed total was.
+type billingUsage[T any] struct {
+	BillingPeriod api.BillingPeriod `json:"billing_period"`
+	ServerTotal   *serverTotal      `json:"server_total,omitempty"`
+	Usage         T                 `json:"usage"`
+}
+
+// serverTotal is the billed transaction figure for the period, which includes
+// background jobs and so differs from the per-app web-transaction totals.
+type serverTotal struct {
+	Transactions int64  `json:"transactions"`
+	Limit        *int64 `json:"limit,omitempty"`
+}
+
+// usageStructuredOutput emits a usage result as JSON, wrapped with the billing
+// period when --billing-period was used. Without it the shape is the bare
+// result, unchanged.
+func usageStructuredOutput[T any](tf usageTimeframe, data T) bool {
+	if tf.billing == nil {
+		return structuredOutput(data)
+	}
+	wrapped := billingUsage[T]{
+		BillingPeriod: tf.billing.BillingPeriod,
+		Usage:         data,
+	}
+	if apm := tf.billing.APM; apm != nil {
+		wrapped.ServerTotal = &serverTotal{Transactions: apm.TotalTransactions, Limit: apm.Limit}
+	}
+	return structuredOutput(wrapped)
+}
+
 // printUsageHeader prints the billing period when the query is scoped to it,
 // otherwise the plain timeframe header.
 func printUsageHeader(tf usageTimeframe) {
diff --git a/cmd/usage_test.go b/cmd/usage_test.go
index 5ac84a9..b887097 100644
--- a/cmd/usage_test.go
+++ b/cmd/usage_test.go
@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"encoding/json"
 	"fmt"
 	"testing"
 
@@ -298,3 +299,96 @@ func TestFormatTransactions(t *testing.T) {
 		})
 	}
 }
+
+func TestFilterApps(t *testing.T) {
+	apps := []api.App{{ID: 1, Name: "one"}, {ID: 6, Name: "six"}}
+
+	all, err := filterApps(apps, 0)
+	require.NoError(t, err)
+	assert.Equal(t, apps, all)
+
+	one, err := filterApps(apps, 6)
+	require.NoError(t, err)
+	assert.Equal(t, []api.App{{ID: 6, Name: "six"}}, one)
+
+	_, err = filterApps(apps, 999)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "app 999 not found")
+}
+
+// Without --billing-period the structured shape is the bare result.
+func TestUsageStructuredOutputWithoutBillingPeriod(t *testing.T) {
+	prev := jsonOutput
+	jsonOutput = true
+	t.Cleanup(func() { jsonOutput = prev })
+
+	out := captureStdout(t, func() {
+		assert.True(t, usageStructuredOutput(usageTimeframe{}, []appUsage{{ID: 6, Name: "six", Transactions: 10}}))
+	})
+
+	var decoded struct {
+		Data []appUsage `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal([]byte(out), &decoded))
+	assert.Equal(t, []appUsage{{ID: 6, Name: "six", Transactions: 10}}, decoded.Data)
+}
+
+// With --billing-period the period and the billed figure travel with the data.
+func TestUsageStructuredOutputWithBillingPeriod(t *testing.T) {
+	prev := jsonOutput
+	jsonOutput = true
+	t.Cleanup(func() { jsonOutput = prev })
+
+	limit := int64(5000)
+	tf := usageTimeframe{
+		billing: &api.OrgUsage{
+			BillingPeriod: api.BillingPeriod{Start: "2026-03-01", End: "2026-03-31"},
+			APM:           &api.APMUsage{TotalTransactions: 1234, Limit: &limit},
+		},
+	}
+
+	out := captureStdout(t, func() {
+		assert.True(t, usageStructuredOutput(tf, []appUsage{{ID: 6, Name: "six", Transactions: 10}}))
+	})
+
+	var decoded struct {
+		Data billingUsage[[]appUsage] `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal([]byte(out), &decoded))
+	assert.Equal(t, "2026-03-01", decoded.Data.BillingPeriod.Start)
+	assert.Equal(t, "2026-03-31", decoded.Data.BillingPeriod.End)
+	require.NotNil(t, decoded.Data.ServerTotal)
+	assert.Equal(t, int64(1234), decoded.Data.ServerTotal.Transactions)
+	require.NotNil(t, decoded.Data.ServerTotal.Limit)
+	assert.Equal(t, int64(5000), *decoded.Data.ServerTotal.Limit)
+	assert.Len(t, decoded.Data.Usage, 1)
+}
+
+// -n selects which rows ship, never the billed total.
+func TestUsageStructuredOutputLimitDoesNotChangeServerTotal(t *testing.T) {
+	prev := jsonOutput
+	jsonOutput = true
+	t.Cleanup(func() { jsonOutput = prev })
+	withLimit(t, 1)
+
+	tf := usageTimeframe{
+		billing: &api.OrgUsage{
+			BillingPeriod: api.BillingPeriod{Start: "2026-03-01", End: "2026-03-31"},
+			APM:           &api.APMUsage{TotalTransactions: 999},
+		},
+	}
+	results := []appUsage{{ID: 1, Transactions: 5}, {ID: 2, Transactions: 3}}
+	shown, total := limitSlice(results)
+	assert.Equal(t, 2, total)
+
+	out := captureStdout(t, func() {
+		assert.True(t, usageStructuredOutput(tf, shown))
+	})
+
+	var decoded struct {
+		Data billingUsage[[]appUsage] `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal([]byte(out), &decoded))
+	assert.Len(t, decoded.Data.Usage, 1)
+	assert.Equal(t, int64(999), decoded.Data.ServerTotal.Transactions)
+}
diff --git a/go.mod b/go.mod
index 45cb793..4dcff0a 100644
--- a/go.mod
+++ b/go.mod
@@ -6,10 +6,10 @@ require (
 	github.com/charmbracelet/bubbles v1.0.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/charmbracelet/x/ansi v0.11.6
 	github.com/guptarohit/asciigraph v0.7.3
 	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.11.1
-	github.com/toon-format/toon-go v0.0.0-20251202084852-7ca0e27c4e8c
 	golang.org/x/term v0.40.0
 )
 
@@ -18,7 +18,6 @@ require (
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/charmbracelet/colorprofile v0.4.1 // indirect
 	github.com/charmbracelet/harmonica v0.2.0 // indirect
-	github.com/charmbracelet/x/ansi v0.11.6 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
 	github.com/charmbracelet/x/term v0.2.2 // indirect
 	github.com/clipperhouse/displaywidth v0.9.0 // indirect
diff --git a/go.sum b/go.sum
index c78d7c8..e7010df 100644
--- a/go.sum
+++ b/go.sum
@@ -62,8 +62,6 @@ github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-github.com/toon-format/toon-go v0.0.0-20251202084852-7ca0e27c4e8c h1:D8lDFovBMZywze1eh9iwMLcYor5f11mHBocLhO7cBe8=
-github.com/toon-format/toon-go v0.0.0-20251202084852-7ca0e27c4e8c/go.mod h1:j/BOnpF2ihnz4lELs99h9mwGJBx/zdleOUCnLLRPCsc=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
diff --git a/internal/api/client.go b/internal/api/client.go
index 270fe42..33d85fd 100644
--- a/internal/api/client.go
+++ b/internal/api/client.go
@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
+	"unicode/utf8"
 )
 
 type Client struct {
@@ -32,12 +33,26 @@ func bodySnippet(body []byte) string {
 		return "(empty response body)"
 	}
 	const max = 200
-	if len(s) > max {
-		return s[:max] + "…"
+	if utf8.RuneCountInString(s) > max {
+		return string([]rune(s)[:max]) + "…"
 	}
 	return s
 }
 
+// statusMessage combines an HTTP status text with a body snippet, dropping the
+// snippet when it only repeats the status (a plain-text "Not Found" body under
+// a 404 would otherwise read "Not Found: Not Found").
+func statusMessage(statusText, snippet string) string {
+	if statusText == "" {
+		return snippet
+	}
+	trimmed := strings.ToLower(strings.Trim(snippet, " .…"))
+	if trimmed != "" && strings.Contains(strings.ToLower(statusText), trimmed) {
+		return statusText
+	}
+	return fmt.Sprintf("%s: %s", statusText, snippet)
+}
+
 func (c *Client) get(path string, params map[string]string) (json.RawMessage, error) {
 	u, err := url.Parse(c.baseURL + path)
 	if err != nil {
@@ -78,7 +93,7 @@ func (c *Client) get(path string, params map[string]string) (json.RawMessage, er
 		if resp.StatusCode >= 400 {
 			return nil, &APIError{
 				StatusCode: resp.StatusCode,
-				Message:    fmt.Sprintf("%s: %s", http.StatusText(resp.StatusCode), bodySnippet(body)),
+				Message:    statusMessage(http.StatusText(resp.StatusCode), bodySnippet(body)),
 			}
 		}
 		return nil, fmt.Errorf("failed to parse response (HTTP %d): %s", resp.StatusCode, bodySnippet(body))
@@ -182,6 +197,7 @@ func (c *Client) GetJobMetrics(appID int, jobID, metricType, from, to string) (*
 	if err := json.Unmarshal(results, &r); err != nil {
 		return nil, err
 	}
+	r.normalizeSeriesNames(metricType)
 	return &r, nil
 }
 
diff --git a/internal/api/client_test.go b/internal/api/client_test.go
index bc195ab..1708511 100644
--- a/internal/api/client_test.go
+++ b/internal/api/client_test.go
@@ -4,7 +4,9 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
+	"unicode/utf8"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -163,11 +165,58 @@ func TestNonJSONErrorResponse(t *testing.T) {
 	apiErr, ok := err.(*APIError)
 	require.True(t, ok, "expected *APIError, got %T: %v", err, err)
 	assert.Equal(t, 404, apiErr.StatusCode)
-	assert.Contains(t, apiErr.Message, "Not Found")
+	assert.Equal(t, "Not Found", apiErr.Message, "status text and an identical body should not be repeated")
 	// The cryptic JSON parse error must not leak through.
 	assert.NotContains(t, err.Error(), "invalid character")
 }
 
+func TestNonJSONErrorResponseKeepsDistinctBody(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		_, _ = w.Write([]byte("upstream timeout"))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-key")
+	_, err := client.ListApps()
+	require.Error(t, err)
+
+	apiErr, ok := err.(*APIError)
+	require.True(t, ok, "expected *APIError, got %T: %v", err, err)
+	assert.Equal(t, "Internal Server Error: upstream timeout", apiErr.Message)
+}
+
+func TestStatusMessage(t *testing.T) {
+	tests := []struct {
+		name       string
+		statusText string
+		snippet    string
+		want       string
+	}{
+		{name: "identical", statusText: "Not Found", snippet: "Not Found", want: "Not Found"},
+		{name: "different case", statusText: "Not Found", snippet: "not found", want: "Not Found"},
+		{name: "trailing period", statusText: "Not Found", snippet: "Not found.", want: "Not Found"},
+		{name: "distinct body", statusText: "Bad Gateway", snippet: "nginx", want: "Bad Gateway: nginx"},
+		{name: "empty body", statusText: "Not Found", snippet: "(empty response body)", want: "Not Found: (empty response body)"},
+		{name: "unknown status", statusText: "", snippet: "boom", want: "boom"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, statusMessage(tt.statusText, tt.snippet))
+		})
+	}
+}
+
+func TestBodySnippetTruncatesByRune(t *testing.T) {
+	body := strings.Repeat("é", 300)
+
+	got := bodySnippet([]byte(body))
+
+	assert.True(t, utf8.ValidString(got), "truncation split a multibyte character")
+	assert.Equal(t, 201, utf8.RuneCountInString(got), "200 runes plus the ellipsis")
+}
+
 func TestMetricPointJSON(t *testing.T) {
 	data := `["2026-02-12T19:15:00Z", 76.51]`
 	var mp MetricPoint
diff --git a/internal/api/jobs_test.go b/internal/api/jobs_test.go
index bd03b03..5747d00 100644
--- a/internal/api/jobs_test.go
+++ b/internal/api/jobs_test.go
@@ -228,3 +228,53 @@ func TestListJobTracesNotFound(t *testing.T) {
 	assert.Equal(t, 404, apiErr.StatusCode)
 	assert.Contains(t, apiErr.Message, "Job not found")
 }
+
+// The latency response carries a "total" sub-series that is the job's total
+// execution time, not latency. Structured output must not present it under
+// a name that says otherwise.
+func TestGetJobMetricsRenamesLatencyTotal(t *testing.T) {
+	results := `{"summaries":{"latency":1500},"series":{"latency":{
+		"Latency":[["2026-01-01T00:00:00Z",1450]],
+		"total":[["2026-01-01T00:00:00Z",85]]}}}`
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(envelope(results)))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-key")
+	m, err := client.GetJobMetrics(6, "ZGVmYXVsdC9NeVdvcmtlcg==", "latency", "from", "to")
+	require.NoError(t, err)
+
+	assert.NotContains(t, m.Series, "total")
+	require.Contains(t, m.Series, ExecutionTimeTotalKey)
+	assert.InDelta(t, 85, m.Series[ExecutionTimeTotalKey][0].Value, 0.01)
+	assert.InDelta(t, 1450, m.Series["Latency"][0].Value, 0.01)
+}
+
+func TestGetJobMetricsKeepsTotalForOtherTypes(t *testing.T) {
+	results := `{"summaries":{"execution_time":110},"series":{"execution_time":{
+		"ActiveRecord":[["2026-01-01T00:00:00Z",30]],
+		"total":[["2026-01-01T00:00:00Z",110]]}}}`
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(envelope(results)))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-key")
+	m, err := client.GetJobMetrics(6, "ZGVmYXVsdC9NeVdvcmtlcg==", "execution_time", "from", "to")
+	require.NoError(t, err)
+
+	assert.Contains(t, m.Series, "total")
+	assert.NotContains(t, m.Series, ExecutionTimeTotalKey)
+}
+
+// Without a "Latency" series the "total" is the latency total and keeps its name.
+func TestNormalizeSeriesNamesLeavesLoneTotal(t *testing.T) {
+	m := &JobMetricsResult{Series: map[string][]MetricPoint{
+		"total": {{Timestamp: "2026-01-01T00:00:00Z", Value: 12}},
+	}}
+	m.normalizeSeriesNames("latency")
+	assert.Contains(t, m.Series, "total")
+}
diff --git a/internal/api/types.go b/internal/api/types.go
index b98f207..9dcf9ae 100644
--- a/internal/api/types.go
+++ b/internal/api/types.go
@@ -181,6 +181,29 @@ func (r *JobMetricsResult) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// ExecutionTimeTotalKey is the name given to the latency response's "total"
+// sub-series, which holds the job's total execution time rather than latency.
+const ExecutionTimeTotalKey = "execution_time_total"
+
+// normalizeSeriesNames renames sub-series whose API name misdescribes their
+// contents, so structured output doesn't hand callers a mislabelled series.
+// The latency response carries both a "Latency" series and a "total" series
+// that is execution time, not queue latency.
+func (r *JobMetricsResult) normalizeSeriesNames(metricType string) {
+	if metricType != "latency" {
+		return
+	}
+	total, ok := r.Series["total"]
+	if !ok {
+		return
+	}
+	if _, hasLatency := r.Series["Latency"]; !hasLatency {
+		return
+	}
+	delete(r.Series, "total")
+	r.Series[ExecutionTimeTotalKey] = total
+}
+
 // Total returns a single series for charting: the only sub-series when there
 // is exactly one, the API-provided "total" sub-series when present (e.g.
 // execution_time returns per-category series plus their total), otherwise the
diff --git a/internal/config/config.go b/internal/config/config.go
index bbd81dc..52a0ad5 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -64,6 +64,9 @@ func Clear() error {
 	if err != nil {
 		return err
 	}
+	if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
+		return err
+	}
 	return os.WriteFile(path, []byte("{}"), 0600)
 }
 
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index fde05c6..5fc6c31 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -73,3 +73,16 @@ func TestGetAPIURLFromEnv(t *testing.T) {
 	t.Setenv("SCOUT_API_URL", "https://custom.com")
 	assert.Equal(t, "https://custom.com", GetAPIURL())
 }
+
+// 'scout auth logout' on a fresh machine, where no config has ever been written.
+func TestClearWithoutExistingConfigDir(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("HOME", tmpDir)
+	t.Setenv("XDG_CONFIG_HOME", tmpDir)
+
+	require.NoError(t, Clear())
+
+	cfg, err := Read()
+	require.NoError(t, err)
+	assert.Equal(t, Config{}, cfg)
+}
diff --git a/internal/output/chart.go b/internal/output/chart.go
index eb11cd5..7516db5 100644
--- a/internal/output/chart.go
+++ b/internal/output/chart.go
@@ -4,41 +4,38 @@ import (
 	"fmt"
 	"math"
 	"strings"
+	"time"
 
 	"github.com/charmbracelet/lipgloss"
 	"github.com/guptarohit/asciigraph"
 	"github.com/scoutapm/scout/internal/api"
 )
 
+// chartPoints is the number of plotted points a series is downsampled to so
+// the chart fits a normal terminal width.
+const chartPoints = 60
+
 func RenderChart(title string, points []api.MetricPoint, summary float64, unit string) string {
+	points = trimPartialBucket(points, time.Now().UTC())
 	if len(points) == 0 {
 		return DimStyle.Render("No data points available.")
 	}
 
 	values := make([]float64, len(points))
-	var min, max, sum float64
-	min = math.MaxFloat64
+	lo, hi, sum := math.MaxFloat64, -math.MaxFloat64, 0.0
 	for i, p := range points {
 		values[i] = p.Value
 		sum += p.Value
-		if p.Value < min {
-			min = p.Value
-		}
-		if p.Value > max {
-			max = p.Value
-		}
+		lo = math.Min(lo, p.Value)
+		hi = math.Max(hi, p.Value)
 	}
 	avg := sum / float64(len(values))
 
-	// Downsample to ~60 points for terminal width
-	if len(values) > 60 {
-		values = downsample(values, 60)
+	if len(values) > chartPoints {
+		values = downsample(values, chartPoints)
 	}
 
-	graph := asciigraph.Plot(values,
-		asciigraph.Height(8),
-		asciigraph.Caption(fmt.Sprintf("  %s", title)),
-	)
+	graph := asciigraph.Plot(values, asciigraph.Height(8))
 
 	var sb strings.Builder
 	sb.WriteString(HeaderStyle.Render(title))
@@ -47,19 +44,52 @@ func RenderChart(title string, points []api.MetricPoint, summary float64, unit s
 	sb.WriteString("\n\n")
 
 	statsStyle := lipgloss.NewStyle().Padding(0, 2)
-	stats := fmt.Sprintf("Avg: %s%s  Min: %s%s  Max: %s%s",
-		formatValue(avg), unit,
-		formatValue(min), unit,
-		formatValue(max), unit,
+	stats := fmt.Sprintf("Avg: %s  Min: %s  Max: %s  Summary: %s",
+		formatStat(avg, unit),
+		formatStat(lo, unit),
+		formatStat(hi, unit),
+		formatStat(summary, unit),
 	)
-	if summary > 0 {
-		stats += fmt.Sprintf("  Summary: %s%s", formatValue(summary), unit)
-	}
 	sb.WriteString(statsStyle.Render(DimStyle.Render(stats)))
 
 	return sb.String()
 }
 
+// trimPartialBucket drops the final point when the time bucket it starts is
+// still filling. The API's most recent bucket is incomplete and usually reads
+// near zero, which would otherwise drag Min and Avg toward zero and put a
+// phantom dip at the right edge of the plot.
+func trimPartialBucket(points []api.MetricPoint, now time.Time) []api.MetricPoint {
+	if len(points) < 3 {
+		return points
+	}
+	last, err := time.Parse(time.RFC3339, points[len(points)-1].Timestamp)
+	if err != nil {
+		return points
+	}
+	prev, err := time.Parse(time.RFC3339, points[len(points)-2].Timestamp)
+	if err != nil {
+		return points
+	}
+	interval := last.Sub(prev)
+	if interval <= 0 {
+		return points
+	}
+	if last.Add(interval).After(now) {
+		return points[:len(points)-1]
+	}
+	return points
+}
+
+// formatStat renders a stat value with its unit, promoting large millisecond
+// values to seconds so the k-scale suffix never reads "kms".
+func formatStat(v float64, unit string) string {
+	if unit == "ms" && math.Abs(v) >= 1000 {
+		return fmt.Sprintf("%.1fs", v/1000)
+	}
+	return formatValue(v) + unit
+}
+
 func formatValue(v float64) string {
 	if v >= 1000 {
 		return fmt.Sprintf("%.1fk", v/1000)
@@ -70,18 +100,27 @@ func formatValue(v float64) string {
 	return fmt.Sprintf("%.2f", v)
 }
 
+// downsample reduces data to target points by keeping the largest-magnitude
+// value of each bucket, so a spike that falls between bucket boundaries still
+// shows up in the plotted line.
 func downsample(data []float64, target int) []float64 {
-	if len(data) <= target {
+	if target <= 0 || len(data) <= target {
 		return data
 	}
 	result := make([]float64, target)
-	ratio := float64(len(data)) / float64(target)
-	for i := 0; i < target; i++ {
-		idx := int(float64(i) * ratio)
-		if idx >= len(data) {
-			idx = len(data) - 1
+	for i := range result {
+		start := i * len(data) / target
+		end := (i + 1) * len(data) / target
+		if end <= start {
+			end = start + 1
+		}
+		peak := data[start]
+		for _, v := range data[start+1 : end] {
+			if math.Abs(v) > math.Abs(peak) {
+				peak = v
+			}
 		}
-		result[i] = data[idx]
+		result[i] = peak
 	}
 	return result
 }
diff --git a/internal/output/chart_test.go b/internal/output/chart_test.go
new file mode 100644
index 0000000..56f4a39
--- /dev/null
+++ b/internal/output/chart_test.go
@@ -0,0 +1,144 @@
+package output
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/scoutapm/scout/internal/api"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// series builds points spaced one minute apart, ending `endsAgo` before now.
+func series(endsAgo time.Duration, values ...float64) []api.MetricPoint {
+	end := time.Now().UTC().Add(-endsAgo)
+	points := make([]api.MetricPoint, len(values))
+	for i, v := range values {
+		ts := end.Add(-time.Duration(len(values)-1-i) * time.Minute)
+		points[i] = api.MetricPoint{Timestamp: ts.Format(time.RFC3339), Value: v}
+	}
+	return points
+}
+
+func TestDownsamplePreservesSpike(t *testing.T) {
+	data := make([]float64, 600)
+	for i := range data {
+		data[i] = 10
+	}
+	data[317] = 999
+
+	got := downsample(data, 60)
+
+	require.Len(t, got, 60)
+	assert.Contains(t, got, 999.0, "downsampling dropped the spike")
+}
+
+func TestDownsampleShortSeriesUnchanged(t *testing.T) {
+	data := []float64{1, 2, 3}
+	assert.Equal(t, data, downsample(data, 60))
+}
+
+func TestDownsampleCoversEveryBucket(t *testing.T) {
+	data := make([]float64, 121)
+	for i := range data {
+		data[i] = float64(i)
+	}
+
+	got := downsample(data, 60)
+
+	require.Len(t, got, 60)
+	// Buckets are contiguous and ascending, so the last bucket must contain
+	// the final value rather than stopping short of it.
+	assert.Equal(t, 120.0, got[59])
+	assert.Less(t, got[0], got[59])
+}
+
+func TestTrimPartialBucketDropsUnclosedBucket(t *testing.T) {
+	now := time.Now().UTC()
+	points := series(30*time.Second, 100, 110, 120, 0)
+
+	got := trimPartialBucket(points, now)
+
+	assert.Len(t, got, 3)
+	assert.Equal(t, 120.0, got[len(got)-1].Value)
+}
+
+func TestTrimPartialBucketKeepsClosedBucket(t *testing.T) {
+	now := time.Now().UTC()
+	points := series(2*time.Hour, 100, 110, 120, 0)
+
+	got := trimPartialBucket(points, now)
+
+	assert.Len(t, got, 4)
+}
+
+func TestTrimPartialBucketIgnoresUnparsableTimestamps(t *testing.T) {
+	points := []api.MetricPoint{
+		{Timestamp: "not-a-time", Value: 1},
+		{Timestamp: "also-not-a-time", Value: 2},
+		{Timestamp: "still-not-a-time", Value: 3},
+	}
+
+	assert.Equal(t, points, trimPartialBucket(points, time.Now().UTC()))
+}
+
+func TestRenderChartExcludesPartialBucketFromStats(t *testing.T) {
+	out := RenderChart("response_time", series(30*time.Second, 100, 110, 120, 0), 110, "ms")
+
+	assert.Contains(t, out, "Min: 100ms")
+	assert.Contains(t, out, "Max: 120ms")
+	assert.NotContains(t, out, "Min: 0ms")
+}
+
+func TestRenderChartPromotesMillisecondsToSeconds(t *testing.T) {
+	out := RenderChart("response_time", series(2*time.Hour, 5700, 5700, 5700), 5700, "ms")
+
+	assert.Contains(t, out, "5.7s")
+	assert.NotContains(t, out, "kms")
+}
+
+func TestRenderChartKeepsUnitForNonMilliseconds(t *testing.T) {
+	out := RenderChart("throughput", series(2*time.Hour, 5700, 5700, 5700), 5700, " rpm")
+
+	assert.Contains(t, out, "5.7k rpm")
+}
+
+func TestRenderChartShowsZeroSummary(t *testing.T) {
+	out := RenderChart("errors", series(2*time.Hour, 1, 2, 3), 0, "")
+
+	assert.Contains(t, out, "Summary: 0")
+}
+
+func TestRenderChartRendersTitleOnce(t *testing.T) {
+	title := "response_time — api/metrics/show"
+
+	out := RenderChart(title, series(2*time.Hour, 1, 2, 3), 2, "ms")
+
+	assert.Equal(t, 1, strings.Count(out, title), "title should be rendered once, not duplicated as a caption")
+}
+
+func TestRenderChartNoPoints(t *testing.T) {
+	assert.Contains(t, RenderChart("errors", nil, 0, ""), "No data points available.")
+}
+
+func TestFormatStat(t *testing.T) {
+	tests := []struct {
+		value float64
+		unit  string
+		want  string
+	}{
+		{5700, "ms", "5.7s"},
+		{999, "ms", "999ms"},
+		{1000, "ms", "1.0s"},
+		{0, "ms", "0ms"},
+		{1500, " rpm", "1.5k rpm"},
+		{0.5, "", "0.50"},
+	}
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("%v%s", tt.value, tt.unit), func(t *testing.T) {
+			assert.Equal(t, tt.want, formatStat(tt.value, tt.unit))
+		})
+	}
+}
diff --git a/internal/output/progress.go b/internal/output/progress.go
index 3aca0a2..e83b205 100644
--- a/internal/output/progress.go
+++ b/internal/output/progress.go
@@ -15,10 +15,10 @@ type doneMsg[T any] struct {
 }
 
 type progressModel[T any] struct {
-	label    string
-	bar      progress.Model
-	result   T
-	done     bool
+	label  string
+	bar    progress.Model
+	result T
+	done   bool
 }
 
 func (m progressModel[T]) Init() tea.Cmd {
diff --git a/internal/output/style.go b/internal/output/style.go
index af594db..a087d54 100644
--- a/internal/output/style.go
+++ b/internal/output/style.go
@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"github.com/charmbracelet/lipgloss"
+	"github.com/charmbracelet/x/ansi"
 )
 
 var (
@@ -20,6 +21,19 @@ var (
 	TableCellStyle   = lipgloss.NewStyle().Padding(0, 1)
 )
 
+// Truncate shortens s to at most width terminal cells, marking the cut with an
+// ellipsis. It counts graphemes rather than bytes, so it never splits a
+// multibyte character or an ANSI escape sequence.
+func Truncate(s string, width int) string {
+	if width <= 0 {
+		return ""
+	}
+	if lipgloss.Width(s) <= width {
+		return s
+	}
+	return ansi.Truncate(s, width, "…")
+}
+
 func StatusColor(status string) lipgloss.Style {
 	switch status {
 	case "active", "open", "ok":
diff --git a/internal/output/table.go b/internal/output/table.go
index 58fa90f..6a77257 100644
--- a/internal/output/table.go
+++ b/internal/output/table.go
@@ -7,6 +7,12 @@ import (
 	"github.com/charmbracelet/lipgloss/table"
 )
 
+// maxCellWidth caps how wide a single table cell may render. Without it one
+// long URI or job name stretches the whole table past a normal terminal width
+// and wraps every row. Structured output is uncapped, so scripts still get the
+// full value.
+const maxCellWidth = 60
+
 func RenderTable(headers []string, rows [][]string) string {
 	if len(rows) == 0 {
 		return DimStyle.Render("No results found.")
@@ -24,7 +30,11 @@ func RenderTable(headers []string, rows [][]string) string {
 		})
 
 	for _, row := range rows {
-		t.Row(row...)
+		capped := make([]string, len(row))
+		for i, cell := range row {
+			capped[i] = Truncate(cell, maxCellWidth)
+		}
+		t.Row(capped...)
 	}
 
 	return fmt.Sprint(t)
diff --git a/internal/output/table_test.go b/internal/output/table_test.go
new file mode 100644
index 0000000..29d5bdc
--- /dev/null
+++ b/internal/output/table_test.go
@@ -0,0 +1,44 @@
+package output
+
+import (
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"github.com/charmbracelet/lipgloss"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRenderTableCapsCellWidth(t *testing.T) {
+	long := strings.Repeat("a", 200)
+
+	out := RenderTable([]string{"URI"}, [][]string{{long}})
+
+	assert.NotContains(t, out, strings.Repeat("a", maxCellWidth+1))
+	assert.Contains(t, out, "…")
+}
+
+func TestRenderTableKeepsShortCells(t *testing.T) {
+	out := RenderTable([]string{"Name"}, [][]string{{"UsersController#show"}})
+
+	assert.Contains(t, out, "UsersController#show")
+	assert.NotContains(t, out, "…")
+}
+
+func TestTruncateIsRuneAware(t *testing.T) {
+	// Byte slicing would cut these three-byte runes mid-character.
+	got := Truncate("日本語です", 5)
+
+	assert.True(t, utf8.ValidString(got))
+	assert.LessOrEqual(t, lipgloss.Width(got), 5)
+	assert.True(t, strings.HasSuffix(got, "…"))
+	assert.Equal(t, "日本語です", Truncate("日本語です", 20))
+}
+
+func TestTruncatePreservesANSI(t *testing.T) {
+	got := Truncate("\x1b[1mhello world\x1b[0m", 6)
+
+	assert.Contains(t, got, "\x1b[1m")
+	assert.LessOrEqual(t, lipgloss.Width(got), 6)
+	assert.Contains(t, got, "hello")
+}
diff --git a/internal/output/tree.go b/internal/output/tree.go
index aeac902..a97e440 100644
--- a/internal/output/tree.go
+++ b/internal/output/tree.go
@@ -96,11 +96,7 @@ func renderSpan(sb *strings.Builder, span api.TraceSpan, totalMs float64, prefix
 	}
 
 	// Format the operation name (pad to 40 chars)
-	op := span.Operation
-	if len(op) > 40 {
-		op = op[:37] + "..."
-	}
-	opFormatted := fmt.Sprintf("%-40s", op)
+	opFormatted := fmt.Sprintf("%-40s", Truncate(span.Operation, 40))
 
 	line := fmt.Sprintf("%s%s%s %6s  %s%s",
 		prefix,
diff --git a/internal/timeutil/parse.go b/internal/timeutil/parse.go
index 3dd30fd..cbd6f11 100644
--- a/internal/timeutil/parse.go
+++ b/internal/timeutil/parse.go
@@ -7,6 +7,34 @@ import (
 	"time"
 )
 
+// maxRelativeDays bounds a relative --from/--to value. Anything further back
+// is a typo rather than a real query, and a large enough value overflows the
+// date arithmetic into a future timestamp.
+const maxRelativeDays = 5 * 365
+
+func isRelativeUnit(unit byte) bool {
+	switch unit {
+	case 'm', 'h', 'd', 'w':
+		return true
+	}
+	return false
+}
+
+// relativeDays converts a relative value to days. It uses float64 so an
+// absurdly large count can be compared against the bound without overflowing.
+func relativeDays(n int, unit byte) float64 {
+	switch unit {
+	case 'm':
+		return float64(n) / (60 * 24)
+	case 'h':
+		return float64(n) / 24
+	case 'w':
+		return float64(n) * 7
+	default:
+		return float64(n)
+	}
+}
+
 func Parse(input string) (time.Time, error) {
 	input = strings.TrimSpace(input)
 	if input == "" {
@@ -17,7 +45,13 @@ func Parse(input string) (time.Time, error) {
 	if len(input) >= 2 {
 		unit := input[len(input)-1]
 		numStr := input[:len(input)-1]
-		if n, err := strconv.Atoi(numStr); err == nil {
+		if n, err := strconv.Atoi(numStr); err == nil && isRelativeUnit(unit) {
+			if n < 0 {
+				return time.Time{}, fmt.Errorf("relative time %q is negative — use a positive value like 1h or 7d", input)
+			}
+			if relativeDays(n, unit) > maxRelativeDays {
+				return time.Time{}, fmt.Errorf("relative time %q is too far in the past (maximum %d days)", input, maxRelativeDays)
+			}
 			now := time.Now().UTC()
 			switch unit {
 			case 'm':
@@ -80,5 +114,10 @@ func ResolveTimeframe(fromStr, toStr string) (string, string, error) {
 		}
 	}
 
+	if !to.After(from) {
+		return "", "", fmt.Errorf("invalid timeframe: --to (%s) must be after --from (%s)",
+			to.Format(time.RFC3339), from.Format(time.RFC3339))
+	}
+
 	return from.Format(time.RFC3339), to.Format(time.RFC3339), nil
 }
diff --git a/internal/timeutil/parse_test.go b/internal/timeutil/parse_test.go
index d954053..6d33ba6 100644
--- a/internal/timeutil/parse_test.go
+++ b/internal/timeutil/parse_test.go
@@ -77,3 +77,49 @@ func TestResolveTimeframeWithFrom(t *testing.T) {
 	diff := toTime.Sub(fromTime)
 	assert.InDelta(t, 1*time.Hour, diff, float64(5*time.Second))
 }
+
+func TestParseRejectsExtremeRelativeValues(t *testing.T) {
+	for _, input := range []string{"999999999999d", "99999w", "2000d", "100000h"} {
+		_, err := Parse(input)
+		require.Error(t, err, input)
+		assert.Contains(t, err.Error(), "too far in the past", input)
+	}
+}
+
+func TestParseRejectsNegativeRelativeValues(t *testing.T) {
+	for _, input := range []string{"-5d", "-1h", "-30m"} {
+		_, err := Parse(input)
+		require.Error(t, err, input)
+		assert.Contains(t, err.Error(), "negative", input)
+	}
+}
+
+func TestParseAllowsValuesInsideTheBound(t *testing.T) {
+	for _, input := range []string{"1h", "30m", "90d", "52w", "1000d"} {
+		_, err := Parse(input)
+		require.NoError(t, err, input)
+	}
+}
+
+func TestResolveTimeframeRejectsReversedRange(t *testing.T) {
+	// --to older than --from: an empty result set today, an error now.
+	_, _, err := ResolveTimeframe("1h", "2h")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "must be after --from")
+
+	_, _, err = ResolveTimeframe("2026-01-02T00:00:00Z", "2026-01-01T00:00:00Z")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "must be after --from")
+}
+
+func TestResolveTimeframeRejectsEmptyRange(t *testing.T) {
+	_, _, err := ResolveTimeframe("2026-01-01T00:00:00Z", "2026-01-01T00:00:00Z")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "must be after --from")
+}
+
+func TestResolveTimeframePropagatesExtremeValues(t *testing.T) {
+	_, _, err := ResolveTimeframe("999999999999d", "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid --from")
+}