@saptools/cf-tail

---

✨ Features

• 📥 Space-wide snapshots — fetch recent logs for every started app in a CF space in parallel, with a configurable concurrency limit.
• 🧬 Chronological merge — every row carries its appName and rows from all apps are merged by timestamp into a single timeline.
• 📡 Multiplexed live stream — one cf-tail stream process tails every app at once, with per-app color, prefixed labels, and auto-rediscovery as apps appear or disappear.
• 🎯 Powerful selection — --apps a,b, --include-regex, --exclude, --exclude-regex to scope the fan-out.
• 🧰 Cross-app filtering — level, search, source, tenant, status range, stream (out/err), --since/--until time windows, --max-rows.
• 📊 Summary view — cf-tail summary aggregates level counts, source buckets, status buckets, tenants, first/last timestamps per app.
• 🚨 Errors shortcut — cf-tail errors is snapshot --level error across the whole space.
• 🔐 Redaction — SAP credentials are redacted before any output or persistence; you can add custom secrets via --extra-secret or programmatic options.
• 🗃️ Bounded local store — aggregate snapshots cached at ~/.saptools/cf-tail-store.json with atomic writes and locking. Per-app raw logs continue to live in the cf-logs store.
• 🧪 Fake-backed e2e — discovery, snapshot, stream, summary flows all pass without live SAP access.

---

📦 Install

# Global CLI
npm install -g @saptools/cf-tail

# Or as a dependency
npm install @saptools/cf-tail
# pnpm add @saptools/cf-tail
# yarn add @saptools/cf-tail

Note

Requires Node.js >= 20 and the official cf CLI on PATH.

---

Updates

Every command first checks npm for a newer @saptools/cf-tail (at most once an hour, one small request with a 2-second timeout) and, when one exists, installs that exact version with the package manager that owns the running binary and re-runs the command you typed on the new version. Both steps are announced on stderr; nothing is printed when the install is already current:

cf-tail: updating 0.2.0 -> 0.3.0 ...
cf-tail: updated to 0.3.0; re-running the command

If the install cannot complete, one stderr line gives the manual command and the command runs on the installed version; that version is not retried for a day. cf-tail self-update forces the check and install now; cf-tail self-update --check only reports.

Control	Effect
SAPTOOLS_AUTO_UPDATE=on|notify|off	on (default) installs and re-runs; notify prints the manual command once per version; off never checks. Applies to every @saptools CLI.
CF_TAIL_AUTO_UPDATE	same values, this CLI only; wins over the global variable
SAPTOOLS_UPDATE_INTERVAL_MINUTES	minutes between checks (default 60; 0 checks on every run)
SAPTOOLS_NPM_REGISTRY	registry to check and install from (default: npm's configured registry, then npmjs)
SAPTOOLS_UPDATE_DEBUG=1	explain on stderr why nothing happened

The updater switches itself off in CI (CI set), under NODE_ENV=test or NO_UPDATE_NOTIFIER, when the binary runs from a source checkout, an npm link or an npx cache, and inside the re-run itself. It never writes to stdout, never asks for input, never uses sudo, and never moves onto a prerelease. Its state lives in ~/.saptools/updates/.

🚀 Quick Start

# 1. Export credentials used for cf api/auth
export SAP_EMAIL="sample@example.com"
export SAP_PASSWORD="sample-password"

# 2. List every started app in a space
cf-tail apps --region ap10 --org sample-org --space sample

# 3. One-shot snapshot of every app, merged by timestamp
cf-tail snapshot --region ap10 --org sample-org --space sample

# 4. Live tail of every app, with per-app colors
cf-tail stream --region ap10 --org sample-org --space sample

---

🧰 CLI

Shared session flags

Flag	Description
--region <key>	CF region key such as ap10
--api-endpoint <url>	Explicit CF API endpoint instead of a region key
--org <name>	CF org name
--space <name>	CF space name
--email <value>	Override SAP_EMAIL
--password <value>	Override SAP_PASSWORD

App-selection flags

Flag	Description
--apps <a,b>	Comma-separated app names to include (alias for --include)
--include <name>	Include a specific app name (repeatable)
--exclude <name>	Exclude a specific app name (repeatable)
--include-regex <pattern>	Include apps matching the regex (repeatable)
--exclude-regex <pattern>	Exclude apps matching the regex (repeatable)

Row filter flags (snapshot, errors, summary, stream)

Flag	Description
--level <name>	trace, debug, info, warn, error, fatal, or all
--search <text>	Case-insensitive substring filter against the searchable row text
--source <text>	Filter rows whose CF source contains the given text
--tenant <id>	Filter rows whose parsed router tenant id matches
--status <range>	Filter router status: 500, 5xx, or 400-499
--stream <value>	Filter by out, err, or all
--since <duration>	Keep rows newer than now - duration (e.g. 30s, 5m, 1h)
--until <duration>	Drop rows older than now - duration
--max-rows <count>	Maximum rows in the rendered output
--newest-first	Render newest-first instead of oldest-first

Output flags

Flag	Description
--json	Emit a single structured JSON object (snapshot, summary)
--ndjson	Emit line-delimited JSON rows (snapshot, stream)
--by-app	Group rendered rows by app instead of merged timeline
--no-color	Disable ANSI colors. Honors NO_COLOR env; FORCE_COLOR overrides for non-TTY pipelines
--show-source	Include the CF source segment in text output
--truncate <chars>	Truncate text-mode messages longer than the given character count

Redaction flags

Flag	Description
--extra-secret <value>	Add a custom redaction (repeatable). Each occurrence is replaced with *** in output and storage

cf-tail apps

cf-tail apps \
  --region ap10 \
  --org sample-org \
  --space sample \
  --include-regex "^demo-" \
  --exclude demo-canary \
  --json

cf-tail snapshot

Fetches recent logs for every matching app in parallel, merges into a single chronological timeline, applies row filters, and optionally persists.

cf-tail snapshot \
  --region ap10 \
  --org sample-org \
  --space sample \
  --apps demo-app,api-app \
  --level error \
  --since 30m \
  --max-rows 100 \
  --json

Snapshot-only flag	Description
--save	Persist redacted per-app snapshots to the cf-logs store and an aggregate entry to the cf-tail store
--concurrency <n>	Maximum apps fetched in parallel (default 4)
--log-limit <count>	Maximum parsed rows and bounded raw-text size per app

cf-tail errors

Shortcut for snapshot --level error:

cf-tail errors --region ap10 --org sample-org --space sample --since 1h

cf-tail summary

Aggregate counts for every matching app:

cf-tail summary \
  --region ap10 \
  --org sample-org \
  --space sample \
  --json

cf-tail stream

Multiplex live logs for every matching app. By default, the runtime re-discovers the app list every 30 seconds, picking up newly started apps and dropping stopped ones. Use --rediscover off (or --rediscover 0s) to disable.

cf-tail stream \
  --region ap10 \
  --org sample-org \
  --space sample \
  --include-regex "^api-" \
  --rediscover 60s

Stream-only flag	Description
--max-lines <count>	Stop after emitting N rows
--rediscover <duration>	Re-discover the app list at this interval (e.g. 30s, 2m, off)
--flush-interval-ms <ms>	Batch window before append events are emitted
--retry-initial-ms <ms>	Initial reconnect delay after unexpected stream exits
--retry-max-ms <ms>	Maximum reconnect delay
--log-limit <count>	Maximum parsed rows and bounded raw-text size per app
--save	Persist bounded redacted stream appends into the cf-logs store
-q, --quiet	Suppress discovery and stream-state messages on stderr (text mode only)

cf-tail store path | list | clear

cf-tail store path
cf-tail store list
cf-tail store list --json
cf-tail store clear

cf-tail --version

Prints the installed @saptools/cf-tail semantic version.

---

📁 Store File

The aggregate cf-tail store lives here:

~/.saptools/cf-tail-store.json

It contains one entry per (apiEndpoint, org, space) with:

• fetchedAt, updatedAt
• appCount, rowCount
• apps: [{ appName, rowCount, truncated }, ...]

Per-app raw text continues to live in the existing cf-logs store at ~/.saptools/cf-logs-store.json (used when you pass --save). The cf-tail store is metadata only.

Prefer readTailStore(), persistTailSnapshot(), cf-tail store path, or cf-tail store list over parsing the file directly.

---

🔐 Security Notes

• The runtime redacts the current SAP email and password before emitting or persisting log content. Pass extraSecrets (programmatic) or --extra-secret <value> (CLI, repeatable) to add custom redaction rules.
• Persisted snapshots are bounded and written with file locking plus atomic replace semantics.
• Neither store file is safe for public repositories. Even after redaction, they still reveal app names, org names, spaces, endpoints, and log content.
• If your application logs contain additional secrets beyond SAP credentials, add custom runtime redaction rules before persisting or forwarding output.

---

❓ FAQ

How is this different from @saptools/cf-logs?

cf-logs is single-app focused: one --app per CLI invocation, one key per store entry, one redaction set. cf-tail is multi-app: discovery, parallel snapshot, multiplexed live stream, chronological merge, cross-app filtering, and an aggregate store. It builds on cf-logs, not against it.

Do I still need cf-logs installed?

cf-tail depends on @saptools/cf-logs automatically. Install @saptools/cf-tail and you get both.

Does stream automatically pick up new apps?

Yes — every --rediscover interval the runtime re-runs cf apps, computes the diff, starts streams for new apps, and stops streams for apps that are no longer started.

How do I scope to a single app?

--apps demo-app (or --include demo-app). Same shape as cf-logs's single-app commands once you scope down.

---

🛠️ Development

From the monorepo root:

pnpm install
pnpm --filter @saptools/cf-tail cspell
pnpm --filter @saptools/cf-tail lint
pnpm --filter @saptools/cf-tail typecheck
pnpm --filter @saptools/cf-tail test:unit
pnpm --filter @saptools/cf-tail test:e2e
pnpm --filter @saptools/cf-tail build
pnpm --filter @saptools/cf-tail check

---

🤝 Author

Maintained by dongtran.