A Node.js client library for the Cloud Foundry API (v2 & v3), with built-in TypeScript support.
Maintained byleotrinh — forked from prosociallearnEU/cf-nodejs-client by Juan Antonio Breña Moral.
Ship faster with AI Dev Team — DISCOUNT 25% - PAY ONE TIME, LIFETIME LIFETIME UPDATE
This library works with any platform that implements the Cloud Foundry API:
| Platform | Provider | Status |
|---|---|---|
| SAP BTP Cloud Foundry | SAP | ✅ Supported |
| Tanzu Platform (formerly Pivotal / TAS) | Broadcom / VMware | ✅ Supported |
| IBM Cloud Foundry | IBM | ✅ Supported |
| SUSE Cloud Application Platform | SUSE | ✅ Supported |
| Open Source Cloud Foundry | Cloud Foundry Foundation | ✅ Supported |
| Any CF-compatible API endpoint | — | ✅ Supported |
SAP BTP Cloud Foundry
Cloud Foundry Architecture
UML Diagram
| Document | Description |
|---|---|
| JSDoc API Reference | Full generated API documentation (all classes, methods, params) |
| Usage Guide | Configuration & API usage examples |
| Service Usage | CF Service integration guide |
| System Architecture | Internal architecture overview |
The JSDoc API Reference covers every public class and method in the library:
| Class | Description | JSDoc |
|---|---|---|
CloudController | CF API info & version | View |
Apps | Application lifecycle (CRUD, start, stop, env, routes) | View |
Organizations | Org management, quotas, domains, users | View |
Spaces | Space management, apps, services per space | View |
Services | Service offerings & plans | View |
ServiceInstances | Service instance CRUD & bindings | View |
ServiceBindings | Service binding management | View |
ServicePlans | Service plan listing & management | View |
UserProvidedServices | User-provided service instances | View |
Routes | Route management & mappings | View |
Domains | Domain management | View |
BuildPacks | Buildpack management | View |
Stacks | Stack listing | View |
Users | User management | View |
Events | Audit events | View |
Jobs | Background tasks | View |
OrganizationsQuota | Org quota definitions | View |
SpacesQuota | Space quota definitions | View |
UsersUAA | UAA authentication (login, tokens) | View |
Logs | Application log streaming | View |
HttpUtils | HTTP request utilities | View |
# Generate JSDoc HTML into doc/ folder
npm run docs
# Generate + serve on localhost:9000 + open browser
npm run docs:servenpm install cf-node-clientconst{ CloudController, UsersUAA, Apps }=require("cf-node-client");// Step 1: Get UAA endpoint from Cloud Controllerconstcc=newCloudController("https://api.<your-cf-domain>");constauthEndpoint=awaitcc.getAuthorizationEndpoint();// Step 2: Authenticateconstuaa=newUsersUAA();uaa.setEndPoint(authEndpoint);consttoken=awaituaa.login("user","pass");// Step 3: Use the tokenconstapps=newApps("https://api.<your-cf-domain>");apps.setToken(token);constresult=awaitapps.getApps();console.log(result.resources);import{CloudController,UsersUAA,Apps,Spaces,Organizations,OAuthToken}from"cf-node-client";constcc=newCloudController("https://api.<your-cf-domain>");constauthEndpoint: string=awaitcc.getAuthorizationEndpoint();constuaa=newUsersUAA();uaa.setEndPoint(authEndpoint);consttoken: OAuthToken=awaituaa.login("user","pass");constapps=newApps("https://api.<your-cf-domain>");apps.setToken(token);constresult=awaitapps.getApps();console.log(result.resources);Built-in TypeScript declarations are included — no additional @types package needed.
| Type | Description |
|---|---|
OAuthToken | UAA authentication token |
FilterOptions | Pagination and query filters |
DeleteOptions | Delete operation options |
ApiResponse<T> | Typed API response wrapper |
CloudControllerBaseOptions | Base constructor options |
See examples/ for more usage patterns.
Find resources by name using server-side filtering — a single API call instead of fetching all resources and looping:
const{ Organizations, Spaces, Apps, ServiceInstances }=require("cf-node-client");constorgs=newOrganizations("https://api.<your-cf-domain>");constspaces=newSpaces("https://api.<your-cf-domain>");constapps=newApps("https://api.<your-cf-domain>");constsi=newServiceInstances("https://api.<your-cf-domain>");orgs.setToken(token);spaces.setToken(token);apps.setToken(token);si.setToken(token);// Find by name (returns first match or null)constorg=awaitorgs.getOrganizationByName("my-org");constspace=awaitspaces.getSpaceByName("dev",orgGuid);// orgGuid optionalconstapp=awaitapps.getAppByName("my-app",spaceGuid);// spaceGuid optionalconstinst=awaitsi.getInstanceByName("my-db",spaceGuid);// spaceGuid optional// Get by GUID (direct lookup)constorg=awaitorgs.getOrganization(orgGuid);constspace=awaitspaces.getSpace(spaceGuid);constapp=awaitapps.getApp(appGuid);constinst=awaitsi.getInstance(instanceGuid);| Resource | List All | Get by GUID | Find by Name | Get ALL (paginated) |
|---|---|---|---|---|
| Organizations | getOrganizations() | getOrganization(guid) | getOrganizationByName(name) | getAllOrganizations(filter?) |
| Spaces | getSpaces() | getSpace(guid) | getSpaceByName(name, orgGuid?) | getAllSpaces(filter?) |
| Apps | getApps() | getApp(guid) | getAppByName(name, spaceGuid?) | getAllApps(filter?) |
| ServiceInstances | getInstances() | getInstance(guid) | getInstanceByName(name, spaceGuid?) | getAllInstances(filter?) |
Works with both v2 (
q=name:X) and v3 (names=X) APIs automatically.
No more manual pagination loops — the library pages through every page and returns a flat array:
constallOrgs=awaitorgs.getAllOrganizations();constallSpaces=awaitspaces.getAllSpaces();constallApps=awaitapps.getAllApps({q: "space_guid:xxx"});constallSIs=awaitsi.getAllInstances();Handles both v2 (next_url) and v3 (pagination.next) transparently. v3 fetches 200 per page; v2 fetches 100 per page.
Opt-in, in-memory cache with configurable TTL (default 30 s). Reduces redundant API calls when the same data is requested multiple times:
// Enable at construction timeconstorgs=newOrganizations(api,{cache: true,cacheTTL: 60000});orgs.setToken(token);awaitorgs.getAllOrganizations();// API call → result cachedawaitorgs.getAllOrganizations();// cache hit — 0 HTTP calls// Toggle at runtimeorgs.enableCache();// default 30 s TTLorgs.enableCache(60000);// custom 60 s TTLorgs.clearCache();// clear entries, keep cache enabledorgs.disableCache();// turn off + clear allAll API calls use v3 by default. No additional configuration needed.
| Resource | Docs |
|---|---|
| Apps | API |
| Spaces | API |
| Service Instances | API |
| Service Bindings | API |
| Organizations | API |
| Users | API |
| Other v3 endpoints | Full v3 API Reference |
Note: CF API v2 is deprecated by Cloud Foundry. Use v2 only if your platform has not yet migrated to v3.
To enable v2, pass { apiVersion: "v2" } when creating any resource instance:
const{ Apps, Spaces, Organizations }=require("cf-node-client");// v2 modeconstapps=newApps("https://api.<your-cf-domain>",{apiVersion: "v2"});constspaces=newSpaces("https://api.<your-cf-domain>",{apiVersion: "v2"});constorgs=newOrganizations("https://api.<your-cf-domain>",{apiVersion: "v2"});| Resource | Docs |
|---|---|
| Apps | API |
| Buildpacks | API |
| Domains | API |
| Jobs | API |
| Organizations | API |
| Organizations Quotas | API |
| Routes | API |
| Services | API |
| Service Bindings | API |
| Service Instances | API |
| Service Plans | API |
| Spaces | API |
| Spaces Quotas | API |
| Stacks | API |
| User Provided Services | API |
| Users | API |
# Run test suite
npm test# Run unit tests only
npm run test:unit
# Code coverage
istanbul cover node_modules/mocha/bin/_mocha -- -R specSee CHANGELOG.md for version history.
Contributions are welcome! We want to make contributing as easy and transparent as possible.
How to contribute:
- Fork the repository
- Create your feature branch (
git checkout -b feature/my-feature) - Write or improve tests — this is the most impactful way to help
- Run the precheck before committing:
This runs TypeScript compilation (
npm run precheck
tsc) and the full test suite (lint + unit tests). Your PR will not be accepted if precheck fails. - Commit your changes (
git commit -m 'feat: add some feature') - Push to the branch (
git push origin feature/my-feature) - Open a Pull Request
First time? Look for issues labeled
good first issue— writing tests is a great way to start. Every PR with new test coverage is highly appreciated!
This fork tracks and resolves issues from the original upstream repositories:
Individual issue docs: docs/issues/
| # | Origin | Issue | Doc |
|---|---|---|---|
| #199 | prosociallearnEU | HANA Cloud DB start/stop control — Fixed v1.0.8 | Details |
| #196 | prosociallearnEU | Copy bits between apps — Fixed v1.0.8 (verified existing) | Details |
| #183 | prosociallearnEU | Log timestamp missing — Fixed v1.0.8 | Details |
| #173 | prosociallearnEU | Respect .cfignore on upload — Fixed v1.0.8 (CfIgnoreHelper utility) | Details |
| #158 | prosociallearnEU | Download droplet from app — Fixed v1.0.8 (verified existing) | Details |
| #157 | prosociallearnEU | Download bits from app — Fixed v1.0.8 (verified existing) | Details |
| #156 | prosociallearnEU | URL validation in constructors — Fixed v1.0.8 (verified existing) | Details |
| #44 | IBM-Cloud | APIKey auth (instead of user/password) — Fixed v1.0.8 | Details |
| #47 | IBM-Cloud | Same-name services in different spaces — Fixed v1.0.8 (verified existing) | Details |
| #15 | IBM-Cloud | getTokenInfo(accessToken) method — Fixed v1.0.8 (verified existing) | Details |
| #198 | prosociallearnEU | Apps.upload() broken on Node 12+ (restler) — Fixed v1.0.6 | Details |
| #50 | IBM-Cloud | Node security alerts (multiple deps) — Fixed v1.0.2 | Details |
| #52 | IBM-Cloud | protobufjs vulnerability — Fixed (v7.0.0) | Details |
| #192 | prosociallearnEU | Async service creation (accepts_incomplete) — Implemented | Details |
| #45 | IBM-Cloud | Events/Logs TypeError at runtime — Fixed | Details |
| #191 | prosociallearnEU | Set environment variables (cf set-env equivalent) | Details |
| #190 | prosociallearnEU | Works with any CF environment + space handling | Details |
| #188 | prosociallearnEU | Travis CI build broken → migrated to GitHub Actions | Details |
| #179 | prosociallearnEU | How to create a CF app (documented) | Details |
| #43 | IBM-Cloud | Any CF env support (documented) | Details |
| # | Origin | Issue | Priority | Doc |
|---|---|---|---|---|
| #161 | prosociallearnEU | Improve JSDocs / TypeScript types (ongoing) | Low | Details |
If you have any questions or find a bug, please create an issue.
Licensed under the Apache License, Version 2.0.