CDS Command Line Interface (CLI)
To use cds from your command line, install package @sap/cds-dk globally:
npm i -g @sap/cds-dkThis guide is available for Node.js and Java.
Use the toggle in the title bar or press v to switch.
cds version
Use cds version to get information about your installed package version:
> cds version @cap-js/asyncapi: 1.0.2 @cap-js/cds-types: 0.8.0 @cap-js/db-service: 1.16.1 @cap-js/openapi: 1.1.1 @cap-js/sqlite: 1.7.8 @sap/cds: 8.6.0 @sap/cds-compiler: 5.6.0 @sap/cds-dk (global): 8.6.1 @sap/cds-fiori: 1.2.8 @sap/cds-foss: 5.0.1 @sap/cds-mtxs: 2.4.2 @sap/eslint-plugin-cds: 3.1.2 Node.js: v20.18.1 your-project: 1.0.0
Using --markdown you can get the information in markdown format:
> cds version --markdown | your-project | <Add your repository here> | | ---------------------- | --------------------------------------- | | @cap-js/asyncapi | 1.0.2 | | @cap-js/cds-types | 0.8.0 | | @cap-js/db-service | 1.16.1 | | @cap-js/openapi | 1.1.1 | | @cap-js/sqlite | 1.7.8 | | @sap/cds | 8.6.0 | | @sap/cds-compiler | 5.6.0 | | @sap/cds-dk (global) | 8.6.1 | | @sap/cds-fiori | 1.2.8 | | @sap/cds-foss | 5.0.1 | | @sap/cds-mtxs | 2.4.2 | | @sap/eslint-plugin-cds | 3.1.2 | | Node.js | v20.18.1 |
cds completion since @sap/cds-dk 7.9.0
The cds command supports shell completion with the tab key for several shells and operating systems.
For Linux, macOS and Windows use the following command to activate shell completion:
cds add completionAfter that, restart your shell (or source the shell configuration) and enjoy shell completion support for all cds commands.
Currently supported shells:
| Operating System | Shell |
|---|---|
| Linux | bash, fish (version 8 or higher), zsh |
| macOS | bash, fish (version 8 or higher), zsh |
| Windows | PowerShell, Git Bash |
| WSL | bash, fish (version 8 or higher), zsh |
To remove the shell completion, run the following command:
cds completion --removeThen source or restart your shell.
cds help
Use cds help to see an overview of all commands:
> cds --help
USAGE
cds <command> [<args>]
cds <src> = cds compile <src>
cds = cds help
COMMANDS
i | init jump-start cds-based projects
a | add add a feature to an existing project
| gen generate models/data using a descriptive prompt [beta]
y | bind bind application to remote services
m | import add models from external sources
c | compile compile cds models to different outputs
p | parse parses given cds models
s | serve run your services in local server
w | watch run and restart on file changes
| mock call cds serve with mocked service
r | repl read-eval-event loop
e | env inspect effective configuration
b | build prepare for deployment
d | deploy deploy to databases or cloud
| subscribe subscribe a tenant to a multitenant SaaS app
| unsubscribe unsubscribe a tenant from a multitenant SaaS app
l | login login to extensible multitenant SaaS app
| logout logout from extensible multitenant SaaS app
| pull pull base model of extensible SaaS app
| push push extension to extensible SaaS app
t | lint run linter for env or model checks
v | version get detailed version information
| completion add/remove cli completion for cds commands
? | help get detailed usage information
Learn more about each command using:
cds help <command> or
cds <command> --help
Use cds help <command> or cds <command> ? to get specific help:
> cds watch --help
SYNOPSIS
cds watch [<project>]
Tells cds to watch for relevant things to come or change in the specified
project or the current work directory. Compiles and (re-)runs the server
on every change detected.
Actually, cds watch is just a convenient shortcut for:
cds serve all --with-mocks --in-memory?
OPTIONS
--port <number>
Specify the port on which the launched server listens.
If you specify '0', the server picks a random free port.
Alternatively, specify the port using env variable PORT.
--ext <extensions>
Specify file extensions to watch for in a comma-separated list.
Example: cds w --ext cds,json,js.
--livereload <port | false>
Specify the port for the livereload server. Defaults to '35729'.
Disable it with value false.
--open <url>
Open the given URL (suffix) in the browser after starting.
If none is given, the default application URL will be opened.
--profile <profile,...>
Specify from which profile(s) the binding information is taken.
Example: cds w --profile hybrid,production
--debug / --inspect <host:port | 127.0.0.1:9229>
Activate debugger on the given host:port.
If port 0 is specified, a random available port will be used.
--inspect-brk <host:port | 127.0.0.1:9229>
Activate debugger on the given host:port and break at start of user script.
If port 0 is specified, a random available port will be used.
SEE ALSO
cds serve --help for the different start options.
cds init
Use cds init to create new projects.
The simplest form creates a minimal Node.js project. For Java, use
cds init --javaIn addition, you can add (most of) the project 'facets' from below right when creating the project. For example to create a project with a sample bookshop model and configuration for SAP HANA, use:
cds init --add sample,hanacds add
Use cds add to gradually add capabilities ('facets') to projects.
The facets built into @sap/cds-dk provide you with a large set of standard features that support CAP's grow-as-you-go approach:
| Feature | Node.js | Java |
|---|---|---|
tiny-sample | ✓ | ✓ |
sample | ✓ | ✓ |
mta | ✓ | ✓ |
cf-manifest | ✓ | ✓ |
helm | ✓ | ✓ |
helm-unified-runtime | ✓ | ✓ |
containerize | ✓ | ✓ |
multitenancy | ✓ | ✓ |
toggles | ✓ | ✓ |
extensibility | ✓ | ✓ |
xsuaa | ✓ | ✓ |
hana | ✓ | ✓ |
postgres | ✓1 | ✓1 |
sqlite | ✓ | ✓ |
h2 | n/a | ✓ |
liquibase | n/a | ✓ |
local-messaging | ✓ | planned |
file-based-messaging | ✓ | planned |
enterprise-messaging | ✓ | planned |
enterprise-messaging-shared | ✓ | planned |
redis-messaging | ✓1 | planned |
kafka | ✓ | ✓ |
approuter | ✓ | ✓ |
connectivity | ✓ | ✓ |
destination | ✓ | ✓ |
html5-repo | ✓ | ✓ |
portal | ✓ | ✓ |
application-logging | ✓ | ✓ |
audit-logging | ✓ | ✓ |
notifications | ✓ | planned |
attachments | ✓ | ✓ |
data | ✓ | ✓ |
http | ✓ | ✓ |
lint | ✓ | ✓ |
pipeline | ✓ | ✓ |
esm | ✓ | n/a |
typer | ✓ | n/a |
typescript | ✓ | n/a |
completion | ✓ | ✓ |
handler | ✓ | ✓ |
1 Only for Cloud Foundry
See the full help text of cds add
> cds add --help
SYNOPSIS
cds add <feature | comma-separated list of features>
Add one or more features to an existing project - grow as you go.
Pick any of these:
completion - shell completion for cds commands
esm - ESM-compatible Node.js project
tiny-sample - add minimal sample files
sample - add sample files including Fiori UI
typer - type generation for CDS models
typescript - add minimum configuration for a bare TypeScript project
handler - handler stubs for service entities, actions and functions
mta - Cloud Foundry deployment using mta.yaml
cf-manifest - Cloud Foundry deployment using manifest files
helm - Kyma deployment using Helm charts
helm-unified-runtime - Kyma deployment using Unified Runtime Helm charts
containerize - containerization using ctz CLI
multitenancy - schema-based multitenancy support
toggles - allow dynamically toggled features
extensibility - tenant-specific model extensibility
side-by-side-extensibility - logic extensibility via extension points
mtx - multitenancy + toggles + extensibility
xsuaa - authentication via XSUAA
ias - authentication via IAS
ams - authorization via AMS
hana - database support for SAP HANA
postgres - database support for PostgreSQL
sqlite - database support for SQLite
h2 - database support for H2
liquibase - database migration using Liquibase
redis - SAP BTP Redis, Hyperscaler Option
attachments - SAP BTP Object Store Service
malware-scanner - SAP Malware Scanning Service
local-messaging - messaging via local event bus
file-based-messaging - messaging via file system
enterprise-messaging - messaging via SAP Enterprise Messaging
enterprise-messaging-shared - messaging via shared SAP Enterprise Messaging
redis-messaging - messaging via Redis
kafka - messaging via Apache Kafka
approuter - dynamic routing using @sap/approuter
connectivity - SAP BTP Connectivity Service
destination - SAP BTP Destination Service
html5-repo - SAP BTP HTML5 Application Repository
portal - SAP BTP Portal Service
application-logging - SAP BTP Application Logging Service
audit-logging - SAP BTP Audit Logging Service
notifications - SAP BTP Notification Service
workzone-standard - SAP BTP Work Zone, Standard Edition
data - add CSV headers for modeled entities
http - add .http files for modeled services
lint - configure cds lint
pipeline - CI/CD pipeline integration
OPTIONS
--for | -4 <profile>
Write configuration data for the given profile.
--force
Overwrite all files in case the target files already exist.
--package <name>
Pull a package from your npm registry.
FEATURE OPTIONS
cds add audit-logging
--plan
Specify the service plan.
cds add cloud-logging
--plan
Override the service plan used for the MTA generation.
--with-telemetry
Add telemetry capabilities.
cds add completion
--shell | -s
<optional> Forces completion setup for a given shell and disables auto detection.
Usually the shell is determined automatically and this is only for cases where the automatic
detection fails. Valid values: bash, fish, gitbash, ps, zsh.
cds add data
--filter | -f
Filter for entities matching the given pattern. If it contains meta
characters like '^' or '*', it is treated as a regular expression,
otherwise as an include pattern, i.e /.*pattern.*/i
--data:for
Deprecated. Use '--filter' instead.
--records | -n
The number of records to be created for each entity.
--content-type | -c
The content type of the data. One of "json" or "csv".
--out | -o
The output target folder.
cds add enterprise-messaging
--cloudevents | -c
Use CloudEvents formatting.
cds add enterprise-messaging-shared
--cloudevents | -c
Use CloudEvents formatting.
cds add handler
--filter | -f
Filter for entities, actions or functions matching the given pattern.
For Node.js, if it contains meta characters like '^' or '*', it is treated as a regular expression,
otherwise as an include pattern, i.e /.*bookshop.*/i
For Java, only '*' and '**' as suffix wildcards are allowed, as in 'my.bookshop.*' or 'my.**'
--out | -o
Custom output directory.
For Java, the default is 'handlers'. For Node.js, the default is 'srv'.
cds add helm
--y
If provided, the default values will be used for all prompts.
cds add http
--filter | -f
Filter for services or entities or actions matching the given pattern. If it contains meta
characters like '^' or '*', it is treated as a regular expression,
otherwise as an include pattern, i.e /.*pattern.*/i
--for-app | -a
Specify the name of the app to generate requests for.
If not specified, localhost and default auth will be used.
--out | -o
The output directory.
By default, an `http` dir is created in either `test/`, `tests/`, `__tests__/`, or at the root level.
--dry
Print the generated requests to the console instead of writing them to a file.
EXAMPLES
cds add sample
cds add multitenancy,hana,xsuaa --for production
cds add data --filter my.namespace.MyEntity
cds add mta
cds add helm
SEE ALSO
cds init
data
Adds files to the project that carry initial data, in either JSON and CSV format.
The simplest form of:
cds add dataadds csv files with a single header line for all entities to the db/data/ folder. The name of the files matches the entities' namespace and name, separated by -.
Filtering since @sap/cds-dk 7.9.0
To create data for some entities only, use --filter. For example:
cds add data --filter bookswould only create data for entity names that include books (case insensitive).
You can use regular expressions for more flexibility and precision. For example, to only match Books, but not Books.texts, use:
cds add data --filter "books$"Special characters like ? or * need escaping or quoting in shells
The escape character is usually the backslash, for example, \?. Quote characters are ' or " with varying rules between shells. Consult the documentation for your shell here.
Sample records since @sap/cds-dk 7.9.0
To create actual data (along with the header line), use --records with a number for how many records you wish to have.
This example creates 2 records for each entity:
cds add data --records 2Watch a short video by DJ Adams to see this in action.
Formats since @sap/cds-dk 7.9.0
By default, the data format is CSV. You can change this to JSON with the --content-type option:
cds add data --content-type jsonThe result could look like this for a typical Books entity from the Bookshop application:
[
{
"ID": 29894036,
"title": "title-29894036",
"author": {
"ID": 1343293
},
"stock": 94,
"texts": [
{ ... }
]
}
]Some details on the generated data
- For the JSON format, structured objects are used instead of flattened properties, for example,
author: { ID: ... }instead ofauthor_ID.The flattened properties would work as well during database deployment and runtime though. Flattened properties are also used in the CSV format. author.IDrefers to a key from the ...Authors.json file that is created at the same time. If the Authors entity is excluded, though, no such foreign key would be created, which cuts the association off.- Data for compositions, like the
textscomposition toBooks.texts, is always created. - A random unique number for each record, 29894036 here, is added to each string property, to help you correlate properties more easily.
- Data for elements annotated with a regular expression using
assert.formatcan be generated using the NPM package randexp, which you need to installed manually. - Other constraints like type formats, enums, and validation constraints are respected as well, in a best effort way.
Interactively in VS Code since @sap/cds-dk 7.9.0
In VS Code, use the commands Generate Model Data as JSON / CSV to insert test data at the cursor position for a selected entity.
http since @sap/cds-dk 7.9.0
Adds .http files with sample read and write requests.
The simplest form of:
cds add httpcreates http files for all services and all entities.
Filtering
See the filter option of add data for the general syntax. In addition, you can filter with a service name:
cds add http --filter CatalogServiceInteractively in VS Code
In VS Code, use the command Generate HTTP Requests to insert request data in an http file for a selected entity or service.
Authentication / Authorization
To local applications
By default, an authorization header with a local mock user is written to the http file, and localhost is the target host.
@server = http://localhost:4004
@auth = Authorization: Basic alice:
### CatalogService.Books
GET {{server}}/odata/v4/admin/Books
{{auth}}
...By default, an authorization header with a local mock user is written to the http file, and localhost is the target host.
@server = http://localhost:8080
### CatalogService.Books
GET {{server}}/odata/v4/admin/Books
{{auth}}
...To remote applications
Use --for-app <cf-appname> to use a JWT token of a remote application. For example:
cds add http --for-app bookshopassumes a remote app named bookshop on CloudFoundry and a JWT token for this app is written to the request file:
@server = https://...
@auth = x-approuter-authorization: bearer ...Cloud login required
For CloudFoundry, use cf login ... and select org and space.
handler since @sap/cds-dk 8.5.0
Generates handler stubs for actions and functions for both Java and Node.js projects.
To generate handler files, run:
cds add handlermvn compile # let Java know what your model looks like
cd srv # following must be run from srv/
cds add handlerThe files contain handlers for
- actions and functions
- service entities (Node.js only)
Filtering
Use the --filter option to create handlers for specific actions/functions or entities.
cds add handler --filter submitOrder
cds add handler --filter Bookscds env
Use cds env to inspect currently effective config settings:
> cds env requires.db
{
impl: '@cap-js/sqlite',
credentials: { url: ':memory:' },
kind: 'sqlite'
}
cds compile
mermaid since @sap/cds-dk 8.0.0
This produces text for a Mermaid class diagram:
cds compile db/schema.cds --to mermaidOutput:
classDiagram
namespace sap_fe_cap_travel {
class `sap.fe.cap.travel.Travel`["Travel"]
class `sap.fe.cap.travel.Booking`["Booking"]
class `sap.fe.cap.travel.Airline`["Airline"]
class `sap.fe.cap.travel.Airport`["Airport"]
class `sap.fe.cap.travel.Flight`["Flight"]
}If wrapped in a markdown code fence of type mermaid, such diagram text is supported by many markdown renderers, for example, on GitHub.
```mermaid
classDiagram
namespace sap_fe_cap_travel {
class `sap.fe.cap.travel.Travel`["Travel"]
...
}
```To customize the diagram layout, use these environment variables when calling cds compile:
CDS_MERMAID_ASSOCNAMES=false|true # show association/composition names
CDS_MERMAID_ELEMENTS=false|all|keys # no, all, or only key elements
CDS_MERMAID_MIN=false|true # remove unused entities
CDS_MERMAID_NAMESPACES=false|true # group entities by namespace
CDS_MERMAID_QUERIES=false|true # show queries/projections
CDS_MERMAID_DIRECTION=TB|BT|LR|RL # layout direction of the diagramInteractively in VS Code
To visualize your CDS model as a diagram in VS Code, open a .cds file and use the dropdown in the editor toolbar or the command CDS: Preview as diagram:
If you don't see the graphics rendered, but only text, install the Markdown Preview Mermaid Support extension for VS Code.
To customize the diagram layout, use these settings in the Cds > Preview category:
- Diagram: Associations
- Diagram: Direction
- Diagram: Elements
- Diagram: Minify
- Diagram: Namespaces
- Diagram: Queries
cds repl
Use cds repl to live-interact with cds' JavaScript APIs in an interactive read-eval-print-loop.
$ cds repl Welcome to cds repl > cds.parse` entity Foo { bar : Association to Bar } entity Bar { key ID : UUID } ` { definitions: { Foo: { kind: 'entity', elements: { bar: { type: 'cds.Association', target: 'Bar' } } }, Bar: ... } } > SELECT.from(Foo) cds.ql { SELECT: { from: { ref: [ 'Foo' ] } } }
There a couple of shortcuts and convenience functions:
.run(a REPL dot commands) allows to start Node.jscds.servers:sh.run cap/samples/bookshopCLI option
--rundoes the same from command line, for example:shcds repl --run cap/samples/bookshopCLI option
--useallows to use the features of acdsmodule, for example:shcds repl --use ql # as a shortcut of that within the repl:jsvar { expr, ref, columns, /* ...and all other */ } = cds.ql.inspectcommand displays objects with configurable depth:sh.inspect cds .depth=1 .inspect CatalogService.handlers .depth=1
See the full help text of cds repl
> cds repl --help
SYNOPSIS
cds repl [ <options> ]
Launches into a read-eval-print-loop, an interactive playground to
experiment with cds' JavaScript APIs. See documentation of Node.js'
REPL for details at http://nodejs.org/api/repl.html
OPTIONS
-r | --run <project>
Runs a cds server from a given CAP project folder, or module name.
You can then access the entities and services of the running server.
It's the same as using the repl's builtin .run command.
-u | --use <cds feature>
Loads the given cds feature into the repl's global context. For example,
if you specify xl it makes the cds.xl module's methods available.
It's the same as doing {ref,val,xpr,...} = cds.xl within the repl.
EXAMPLES
cds repl --run bookshop
cds repl --run .
cds repl --use cds.ql
SEE ALSO
cds eval to evaluate and execute JavaScript.
Debugging with cds debug beta
cds debug lets you debug Node.js applications in Chrome DevTools running locally or in Cloud Foundry.
To debug remote applications in the currently targeted CF space, run:
$ cds debug Opening SSH tunnel for CF app 'bookshop-srv' Opening Chrome DevTools at devtools://devtools/bundled/inspector.html?ws=...
This opens an SSH tunnel, puts the application in debug mode, and connects and opens the debugger of Chrome DevTools.
Without an app name, cds debug starts cds watch --debug locally:
$ cds debug Starting 'cds watch --debug' ... Debugger listening on ws://127.0.0.1:9229/... Opening Chrome DevTools at devtools://devtools/bundled/inspector.html?ws=... [cds] - ...
Scale to one application instance only
We recommend to only scale to one app instance on SAP BTP Cloud Foundry, as then your request is guaranteed to hit this one instance. If you scale out to more instances, only some of your requests will hit the instance that the debugger is connected to. This can result in 'missed breakpoints'.
However, it's possible to route a request to a specific instance, which is useful if you can't reduce the number of app instances.
Debugging with cds watch
Start cds watch and enter debug. This restarts the application in debug mode. Similarly, debug-brk will start debug mode, but pause the application at the first line, so that you can debug bootstrap code.
If you do this in VS Code's integrated terminal with the 'Auto Attach' feature enabled, debugging starts right away. If you executed cds watch on a standalone terminal, you can still attach a Node.js debugger to the process.
For example:
- In VS Code, use the Debug: Attach to Node Process command.
- In Chrome browser, just open chrome://inspect and click Inspect.