--- description: > Available commands of the cds command line client. --- # CDS Command Line Interface (CLI) {#cli} To use `cds` from your command line, install package `@sap/cds-dk` globally: ```sh npm i -g @sap/cds-dk ``` [[toc]] ## cds version Use `cds version` to get information about your installed package version: Using `--markdown` you can get the information in markdown format: ## cds completion 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: ```sh cds add completion ``` After 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: ```sh cds completion --remove ``` Then source or restart your shell. ## cds help Use `cds help` to see an overview of all commands: Use `cds help ` or `cds ?` to get specific help: ## cds init Use `cds init` to create new projects. The simplest form creates a minimal project. In addition, you can add (most of) the project 'facets' from [below](#cds-add) right when creating the project. For example to create a Node.js project with a sample bookshop model and configuration for SAP HANA, use: ```sh cds init --nodejs --add sample,hana ``` To create just a basic Node.js or Java project, use ```sh cds init --nodejs # OR cds init --java ``` ::: details See the full help text of `cds init` ::: ## cds 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` | | | | `containerize` | | | | `kyma` | | | | `multitenancy` | | | | `toggles` | | | | `extensibility` | | | | `xsuaa` | | | | `ias` | | | | `ams` | | | | `hana` | | | | `postgres` | 1 | 1 | | `sqlite` | | | | `h2` | | | | `liquibase` | | | | `local-messaging` | | | | `file-based-messaging` | | | | `enterprise-messaging` | | | | `enterprise-messaging-shared` | | | | `redis-messaging` | 1 | | | `kafka` | | | | `approuter` | | | | `connectivity` | | | | `destination` | | | | `html5-repo` | | | | `portal` | | | | `application-logging` | | | | `audit-logging` | | | | `notifications` | | | | `attachments` | | | | [`data`](#data) | | | | [`http`](#http) | | | | `lint` | | | | `pipeline` | | | | `esm` | | | | `typer` | | | | `typescript` | | | | `completion` | | | | [`handler`](#handler) | | | > 1 Only for Cloud Foundry
::: details See the full help text of `cds add` ::: ### sample {.add} Creates a bookshop application including custom code (Node.js or Java) and a UI with [SAP Fiori Elements](../guides/uis/fiori). ```sh cds add sample ``` This corresponds to the result of the [_Getting Started in a Nutshell_ guide](../get-started/bookshop). ### tiny-sample {.add} Creates a minimal CAP application without UI. ```sh cds add tiny-sample ``` ### data {.add} Adds files to the project that carry initial data, in either JSON and CSV format. The simplest form of: ```sh cds add data ``` adds _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 {#data-filtering} To create data for some entities only, use `--filter`. For example: ```sh cds add data --filter books ``` would 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: ```sh cds add data --filter "books$" ``` ::: details 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 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: ```sh cds add data --records 2 ``` [Watch a short video by DJ Adams to see this in action.](https://www.youtube.com/shorts/_YVvCA2oSco){.learn-more} #### Formats By default, the data format is _CSV_. You can change this to JSON with the `--content-type` option: ```sh cds add data --content-type json ``` The result could look like this for a typical _Books_ entity from the _Bookshop_ application: ```jsonc [ { "ID": 29894036, "title": "title-29894036", "author": { "ID": 1343293 }, "stock": 94, "texts": [ { ... } ] } ] ``` ::: details Some details on the generated data - For the _JSON_ format, _structured_ objects are used instead of flattened properties, for example, `author: { ID: ... }` instead of `author_ID.` The flattened properties would work as well during database deployment and runtime though. Flattened properties are also used in the _CSV_ format. - `author.ID` refers 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 `texts` composition to `Books.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.format`](../guides/services/constraints#assertformat) can be generated using the NPM package [randexp](https://www.npmjs.com/package/randexp), which you need to installed manually. - Other constraints like [type formats](../cds/types), [enums](../cds/cdl#enums), and [validation constraints](../guides/services/constraints) are respected as well, in a best effort way. ::: #### Interactively in VS Code In [VS Code](./cds-editors#vscode), use the commands _Generate Model Data as JSON / CSV_ to insert test data at the cursor position for a selected entity. ### http {.add} Adds `.http` files with sample read and write requests. The simplest form of: ```sh cds add http ``` creates `http` files for all services and all entities. #### Filtering {#http-filtering} See the filter option of [`add data`](#data-filtering) for the general syntax. In addition, you can filter with a service name: ```sh cds add http --filter CatalogService ``` #### Interactively in VS Code In [VS Code](./cds-editors#vscode), 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. ::: code-group ```http [Node.js] @server = http://localhost:4004 @auth = Authorization: Basic alice: ### CatalogService.Books GET {{server}}/odata/v4/admin/Books {{auth}} ... ``` ```http [Java] @server = http://localhost:8080 ### CatalogService.Books GET {{server}}/odata/v4/admin/Books ... ``` ::: [Learn more about mock users in Node.js.](../node.js/authentication#mock-users){.learn-more} [Learn more about mock users in Java.](../java/security#mock-users){.learn-more} ##### -> To remote applications Use `--for-app ` to use a JWT token of a remote application. For example: ```sh cds add http --for-app bookshop ``` This assumes a remote app named `bookshop` on CloudFoundry and a JWT token for this app is written to the request file: ```http @server = https://... @auth = x-approuter-authorization: bearer ... ``` ::: details Cloud login required For CloudFoundry, use `cf login ...` and select org and space. ::: ### handler {.add} Generates handler stubs for actions and functions for both Java and Node.js projects. To generate handler files, run: ::: code-group ```sh [Node.js] cds add handler ``` ```sh [Java] mvn compile # let Java know what your model looks like cds add handler ``` ::: The files contain handlers for - actions and functions - service entities (Node.js only) #### Filtering {#handler-filtering} Use the `--filter` option to create handlers for specific actions/functions or entities. ```sh cds add handler --filter submitOrder cds add handler --filter Books ``` ## cds env Use `cds env` to inspect currently effective config settings of your Node.js application: ::: details See the full help text of `cds env` ::: ::: tip Inspect configuration for Java applications While `cds env` does _not_ show the [runtime SpringBoot configuration for CAP Java applications](../java/developing-applications/configuring), you can still use it to learn about _designtime_ configuration, which applies to Java applications as well. Examples are build tasks (`cds env build.tasks`) or build plugins (`cds env plugins`).
Also, the [multitenancy sidecar](../java/multitenancy) is a Node.js application, for which `cds env` shows the entire configuration if executed in the _mtx/sidecar_ folder. ::: ## cds compile Compiles the specified models to [CSN](../cds/csn) or other formats. [See simple examples in the getting started page](../get-started/bookshop).{.learn-more} [For the set of built-in compile 'formats', see the `cds.compile.to` API](../node.js/cds-compile#cds-compile-to-).{.learn-more} In addition, the following formats are available: ### mermaid {.compile} This produces text for a [Mermaid class diagram](https://mermaid.js.org/syntax/classDiagram.html): ```sh cds compile db/schema.cds --to mermaid ``` Output: ```log 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](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams). ````md ```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`: ```sh 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 diagram ```
#### Interactively 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_: ![The screenshot is described in the accompanying text.](assets/mermaid-preview.png) {style="filter: drop-shadow(0 2px 5px rgba(0,0,0,.40));"} If you don't see the graphics rendered, but only text, install the [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) extension for VS Code. To customize the diagram layout, use these settings in the _Cds > Preview_ category: - [Diagram: Associations](vscode://settings/cds.preview.diagram.associations) - [Diagram: Direction](vscode://settings/cds.preview.diagram.direction) - [Diagram: Elements](vscode://settings/cds.preview.diagram.elements) - [Diagram: Minify](vscode://settings/cds.preview.diagram.minify) - [Diagram: Namespaces](vscode://settings/cds.preview.diagram.namespaces) - [Diagram: Queries](vscode://settings/cds.preview.diagram.queries) ## cds export With `cds export` you create an API client package to be used for data exchange via CAP-level Service integration ("Calesi"). Define data provider services in your CDS model that serve as an interface to your data, placing each data provider service in a separate file. For the [xflights](https://github.com/capire/xflights) sample app, an API that provides information about flights, airports, and airlines could look like this: ::: code-group ```cds [srv/data-service.cds] using { sap.capire.flights as my } from '../db/schema'; namespace sap.capire.flights; @hcql @rest @odata service FlightsService { @readonly entity Flights as projection on my.Flights; @readonly entity Airlines as projection on my.Airlines; @readonly entity Airports as projection on my.Airports; } ``` ::: Then create an API client package for this service: ```sh cds export srv/data-service.cds ``` The command generates the API client package into a new folder _apis/data-service_. ![The screenshot is described in the accompanying text.](assets/cds-export.png) {style="filter: drop-shadow(0 2px 5px rgba(0,0,0,.40));"} The `service.csn` contains only the interface defined in the service, removing the query part of the entities and all the underlying model. In addition (and as shown in the screenshot): - with the `--texts` option, i18n bundles are included with the localized metadata relevant for the interface - with the `--data` option, initial data that exactly matches the structure of the entities in the API is included - with the `--plugin` option, a `cds-plugin.js` entrypoint file is included for plug & play `cds export` also adds a _package.json_. The package name combines the application name (from the main _package.json_) with the file name of the data service. In our example, this results in `@capire/xflights-data-service`. You can change this name as appropriate. You can then publish the generated package, for example, via `npm publish`. To consume the API in another CAP application: 1. Import the API package with `npm add` 2. Define consumption views on the imported entities 3. Use them in your model as if they were local entities 4. Add custom code to access the data in the provider app via any of the offered protocols Have a look at the [xtravels](https://github.com/capire/xtravels) sample app for an example of using an API client package. :::warning Do not use EDMX to exchange API information Prefer exporting and importing API packages via `cds export` and `npm add`. **Do not use** EDMX (or OpenAPI) as intermediate format for exchanging API information between CAP applications, as you might loose information. ::: ## cds watch Use `cds watch` to watch for changed files, restarting your Node.js server. ::: details See the full help text of `cds watch` ::: ::: tip Watch for Java For CAP Java applications, you can use [`mvn cds:watch`](../java/developing-applications/running#cds-watch) instead. ::: ### Includes and Excludes Additional watched or ignored paths can be specified via CLI options: ```sh cds watch --include ../other-app --exclude .idea/ ``` ## 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](https://nodejs.org/en/learn/command-line/how-to-use-the-nodejs-repl#dot-commands)) allows to start Node.js `cds.server`s: ```sh .run cap/samples/bookshop ``` - CLI option `--run` does the same from command line, for example: ```sh cds repl --run cap/samples/bookshop ``` - CLI option `--use` allows to use the features of a `cds` module, for example: ```sh cds repl --use ql # as a shortcut of that within the repl: ``` ```js var { expr, ref, columns, /* ...and all other */ } = cds.ql ``` - `.inspect` command displays objects with configurable depth: ```sh .inspect cds .depth=1 .inspect CatalogService.handlers .depth=1 ``` ::: details See the full help text of `cds repl` ::: ::: tip Repl for Java `cds repl` does not run Java code, but can still be useful: For example, if you work on Node.js things that make use of Node.js APIs. ::: ## Debugging with `cds debug` {#cds-debug} `cds debug` lets you debug applications running locally or remotely on SAP BTP Cloud Foundry. Local applications will be started in debug mode, while (already running) remote applications are put into debug mode. To debug an application on Cloud Foundry, the following is important: - You're logged in to the space where the application is deployed to. - You have developer permissions in that space. → [Space Developer role](https://help.sap.com/docs/btp/sap-business-technology-platform/about-roles-in-cloud-foundry-environment) - The app is running and [reachable through SSH](https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html#check-ssh-permissions). Effectively, run: ```sh cf login # select the correct org and space here cf ssh-enabled # to check if SSH is enabled ``` ::: tip Scale to one application instance only We recommend to only scale to a _single_ 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](https://docs.cloudfoundry.org/devguide/deploy-apps/routes-domains.html#surgical-routing), which is useful if you can't reduce the number of app instances. ::: ::: warning Cloud Foundry's HTTP health checks kill paused containers While paused at a breakpoint, the Node.js event loop is frozen and the app cannot respond to Cloud Foundry's `http` health probe. As a consequence, Cloud Foundry marks the container unhealthy and destroys it within seconds. Instead, switch the health check to `process` for the duration of the debug session: ```sh cf set-health-check process cf restart ``` Restore it afterwards: ```sh cf set-health-check http ``` `cds debug` detects this situation and prompts you to confirm before continuing. Note that the setting is overwritten on the next `cds up` unless persisted in `mta.yaml`. ::: ### Node.js Applications #### Remote Applications Run the following, to debug remote Node.js applications in the currently targeted CF space: 
$ cds debug <app-name>

Opening SSH tunnel on 9229:127.0.0.1:9229
Opening Chrome DevTools at devtools://devtools/bundled/inspector.html?ws=...

> Keep this terminal open while debugging.
This opens an [SSH tunnel](https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html), puts the application in debug mode, and connects and opens the [debugger of Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript).