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.7.0 @cap-js/db-service: 1.14.1 @cap-js/openapi: 1.0.7 @cap-js/sqlite: 1.7.5 @sap/cds: 8.4.0 @sap/cds-compiler: 5.4.0 @sap/cds-dk (global): 8.4.0 @sap/cds-fiori: 1.2.7 @sap/cds-foss: 5.0.1 @sap/cds-mtxs: 2.3.0 @sap/eslint-plugin-cds: 3.1.1 Node.js: v20.18.0 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.7.0 | | @cap-js/db-service | 1.14.1 | | @cap-js/openapi | 1.0.7 | | @cap-js/sqlite | 1.7.5 | | @sap/cds | 8.4.0 | | @sap/cds-compiler | 5.4.0 | | @sap/cds-dk (global) | 8.4.0 | | @sap/cds-fiori | 1.2.7 | | @sap/cds-foss | 5.0.1 | | @sap/cds-mtxs | 2.3.0 | | @sap/eslint-plugin-cds | 3.1.1 | | Node.js | v20.18.0 |
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
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 --add 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 | ✓ | ✓ |
typer | ✓ | n/a |
typescript | ✓ | n/a |
completion | ✓ | ✓ |
handler | n/a | ✓ |
1 Only for Cloud Foundry
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.3.0
Generates handler stubs for actions and functions in Java projects.
Execute the following from the srv directory of the project to generate handler files for all actions and functions:
cds add handlerFiltering
Use the --filter option to create handlers for specific actions and functions.
cds add handler --filter submitOrderMore Options
| Option | Description |
|---|---|
--out | Specify custom output directories |
--force | Overwrite existing files |
cds 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 Node.js APIs:
$ cds repl Welcome to cds repl > SELECT.from(Foo) Query { SELECT: { from: { ref: [ 'Foo' ] } } } > cds.requires.db { impl: '@cap-js/sqlite', credentials: { url: ':memory:' }, kind: 'sqlite' }
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.