status	synopsis
released	Available commands of the <code>cds</code> command line client

CDS Command Line Interface (CLI) {#cli}

To use cds from your command line, install package @sap/cds-dk globally:

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:

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:

cds completion --remove

Then source or restart your shell.

cds help

Use cds help to see an overview of all commands:

Use cds help <command> or cds <command> ? to get specific help:

cds init

Use cds init to create new projects.

The simplest form creates a minimal Node.js project. For Java, use

cds init --java

In 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,hana

::: 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`
`helm-unified-runtime`
`containerize`
`multitenancy`
`toggles`
`extensibility`
`xsuaa`
`hana`
`postgres`	¹	¹
`sqlite`
`h2`
`liquibase`
`local-messaging`
`file-based-messaging`
`enterprise-messaging`
`enterprise-messaging-shared`
`redis-messaging`	¹
`kafka`
`approuter`
`connectivity`
`destination`
`html5-repo`
`portal`
`application-logging`
`audit-logging`
`notifications`
`attachments`
`data`
`http`
`lint`
`pipeline`
`esm`
`typer`
`typescript`
`completion`
`handler`

¹ Only for Cloud Foundry

::: details See the full help text of cds add

:::

data {.add}

Adds files to the project that carry initial data, in either JSON and CSV format.

The simplest form of:

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:

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:

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:

cds add data --records 2

Watch a short video by DJ Adams to see this in action.{.learn-more}

Formats

By default, the data format is CSV. You can change this to JSON with the --content-type option:

cds add data --content-type json

The 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": [
      { ... }
    ]
  }
]

::: 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 can 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

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 {.add}

Adds .http files with sample read and write requests.

The simplest form of:

cds add http

creates http files for all services and all entities.

Filtering {#http-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 CatalogService

Interactively 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 bookshop

assumes 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 ...

::: 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

cds add handler

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.

cds add handler --filter submitOrder
cds add handler --filter Books

cds env

Use cds env to inspect currently effective config settings:

::: details See the full help text of cds env

:::

cds compile

Compiles the specified models to CSN or other formats.

See simple examples in the getting started page.{.learn-more}

For the set of built-in compile 'formats', see the cds.compile.to API.{.learn-more}

In addition, the following formats are available:

mermaid {.compile}

This produces text for a Mermaid class diagram:

cds compile db/schema.cds --to mermaid

Output:

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 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:

{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 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 watch

Use cds watch to watch for changed files, restarting your server.

::: details See the full help text of cds watch

:::

Includes and Excludes

Additional watched or ignored paths can be specified via CLI options:

cds watch --include ../other-app --exclude .idea/

Alternatively, you can add these paths through settings cds.watch.include: ["../other-app"] and cds.watch.exclude: [".idea"] to your project configuration.

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.js cds.servers:
```
.run cap/samples/bookshop
```
CLI option --run does the same from command line, for example:
```
cds repl --run cap/samples/bookshop
```

CLI option --use allows to use the features of a cds module, for example:

cds repl --use ql # as a shortcut of that within the repl:

var { expr, ref, columns, /* ...and all other */ } = cds.ql

.inspect command displays objects with configurable depth:

.inspect cds .depth=1
.inspect CatalogService.handlers .depth=1

::: details See the full help text of cds repl

:::

Debugging with `cds debug` {.nodejs}

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 bookshop-srv

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cds-cli.md

cds-cli.md

CDS Command Line Interface (CLI) {#cli}

cds version

cds completion

cds help

cds init

cds add

data {.add}

Filtering {#data-filtering}

Sample records

Formats

Interactively in VS Code

http {.add}

Filtering {#http-filtering}

Interactively in VS Code

Authentication / Authorization

To local applications

To remote applications

handler {.add}

Filtering {#handler-filtering}

cds env

cds compile

mermaid {.compile}

Interactively in VS Code

cds watch

Includes and Excludes

cds repl

Debugging with `cds debug` {.nodejs}

Files

cds-cli.md

Latest commit

History

cds-cli.md

File metadata and controls

CDS Command Line Interface (CLI) {#cli}

cds version

cds completion

cds help

cds init

cds add

data {.add}

Filtering {#data-filtering}

Sample records

Formats

Interactively in VS Code

http {.add}

Filtering {#http-filtering}

Interactively in VS Code

Authentication / Authorization

To local applications

To remote applications

handler {.add}

Filtering {#handler-filtering}

cds env

cds compile

mermaid {.compile}

Interactively in VS Code

cds watch

Includes and Excludes

cds repl

Debugging with cds debug {.nodejs}

Debugging with `cds debug` {.nodejs}