@saptools/cf-request-runner

---

✨ Features

• 🌍 Root Endpoint Discovery — fetches root service documents and catalogs from a deployed CAP service dynamically.
• 🟢 Deep Entity Discovery — reads OData $metadata before falling back to service documents to infer entity and operation endpoints.
• ⚡ CF SSH Fallback — if runtime requests are blocked or hidden, falls back to cf ssh to run a headless script parsing .cds definitions.
• 🧭 Zero Configuration — seamlessly integrates with your active Cloud Foundry CLI (cf target) session. No complex credential management required.
• 🗄️ Programmatic API — exports fully typed methods for deep integrations in other Node.js apps.
• 📋 Copy-Ready Curl — emits ready-to-run curl commands for each endpoint/method with the resolved bearer token already injected.
• 🧪 Interactive Runner — select an endpoint and method, enter JSON for write requests, and print the formatted response from the CLI.
• 🧠 Smart Fallbacks — safely handles missing cf CLI sessions, invalid tokens, or restricted network environments.

---

📦 Install

npm install -g @saptools/cf-request-runner

Note

Requires Node.js ≥ 20 and the official cf CLI installed and targeted to a space.

---

Updates

Every command first checks npm for a newer @saptools/cf-request-runner (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-request-runner: updating 0.3.0 -> 0.4.0 ...
cf-request-runner: updated to 0.4.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. This CLI is a single command with required options, so it has no self-update subcommand; run npm install -g @saptools/cf-request-runner@latest to update by hand.

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_REQUEST_RUNNER_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. Target your CF space
cf target -o my-org -s dev

# 2. Run the request runner discovery
cf-request-runner --app my-cap-app --url https://my-cap-app.cfapps.us10.hana.ondemand.com

# 3. Output as JSON for programmatic consumption
cf-request-runner -a my-cap-app -u https://... --json | jq '.'

# 4. Generate copy-ready curl commands
cf-request-runner -a my-cap-app -u https://... --curl

# 5. Run an endpoint interactively
cf-request-runner -a my-cap-app -u https://... --interactive

---

🧰 CLI

cf-request-runner

Executes the endpoint discovery script on a running application.

cf-request-runner --app <appId> --url <baseUrl>

Flag	Shorthand	Description	Required
--app <name>	-a	Cloud Foundry application name.	Yes
--url <baseUrl>	-u	Base URL of the deployed application.	Yes
--cf-home <dir>		Custom CF_HOME directory if using an isolated CF session.	No
--token <bearerToken>		Bearer token override. Prefer CF_REQUEST_RUNNER_TOKEN for sensitive tokens.	No
--json		Output the results in strict JSON format.	No
--out <filePath>		Save JSON output to a specific file. Missing parent directories are created automatically.	No
--curl		Output copy-ready curl commands for every discovered endpoint and method. Includes the resolved bearer token when available.	No
--interactive	-i	Select and execute a discovered endpoint from the CLI. Prompts for JSON payloads on write methods.	No
--help	-h	Display help for command.	No

Copy and run requests

Generate curl commands for all discovered endpoint/method combinations:

cf-request-runner -a my-cap-app -u https://my-cap-app.example.com --curl

Warning

--curl intentionally includes the resolved bearer token in the Authorization header so commands are immediately runnable. Treat this output as sensitive and avoid pasting it into logs or chat.

Run a request interactively from the CLI:

cf-request-runner -a my-cap-app -u https://my-cap-app.example.com --interactive

Interactive mode prompts for an endpoint, a supported method, and a JSON payload for POST, PUT, and PATCH requests, then prints the response status, headers, and body.

For token-based runs, prefer an environment variable so the bearer token is not saved in shell history:

CF_REQUEST_RUNNER_TOKEN="$TOKEN" cf-request-runner -a my-cap-app -u https://my-cap-app.example.com --json

---

❓ FAQ

Why do I need to pass the base URL manually?

The Cloud Foundry CLI can return multiple routes for a single app. Passing the exact base URL ensures we are calling the correct public-facing router, especially in complex landscapes.

Does this work for non-CAP applications?

While primarily built for SAP CAP (which exposes $metadata and endpoints), the CF SSH fallback strictly scans for .cds files. Non-CAP applications might not yield full results.

---

🛠️ Development

From the monorepo root:

pnpm install
pnpm --filter @saptools/cf-request-runner build
pnpm --filter @saptools/cf-request-runner typecheck
pnpm --filter @saptools/cf-request-runner test:unit
pnpm --filter @saptools/cf-request-runner test:e2e

---

🌐 Related

• 🔐 @saptools/cf-sync — Map your SAP BTP Cloud Foundry topology and HANA app bindings.
• 🗂️ saptools monorepo — the full toolbox.

---

👨‍💻 Author

dongtran ✨

📄 License

MIT

---

Made with ❤️ to make your work life easier!