🏃 @saptools/cf-request-runner

Auto-discover all API endpoints of an SAP CAP CDS service deployed on Cloud Foundry.

Automatically walk your remote CAP service documents, OData $metadata, and endpoints catalog, perform deep entity expansion, and safely fall back to container SSH to parse .cds files — no more guessing routes or reading manual documentation.

Install • Quick Start • CLI • FAQ

✨ 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

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.

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!