Skip to content

cds-cli.md

Latest commit

 

History

History
692 lines (485 loc) · 23.8 KB

cds-cli.md

File metadata and controls

692 lines (485 loc) · 23.8 KB
status released
synopsis Available commands of the <code>cds</code> command line client
<script setup> import { h } from 'vue' const X = () => h('span', { class: 'ga', title: 'Available' }, ['✓'] ) const Na = () => h('i', { class: 'na', title: 'not applicable' }, ['n/a'] ) const D = () => h('i', { class: 'prog', title: 'in progress' }, ['in prog.'] ) const O = () => h('i', { class: 'plan', title: 'planned' }, ['planned'] ) const C = () => h('i', { class: 'contrib', title: 'contributions welcome' }, ['contrib?'] ) const Ac = () => h('i', { class: 'contrib', title: 'active contributions' }, ['contrib'] ) </script> <style scoped lang="scss"> .ga { color: var(--vp-c-green-2);} .na { color: gray; font-size:90%; } .prog { color: var(--vp-c-green-3); font-size:90%; font-weight:500; } .plan { color: gray; font-size:90% } .contrib { color: gray; font-size:90% } .add::before { content: 'cds add '; color: #999 } .compile::before { content: 'cds compile --to '; color: #999 } </style>

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
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
http
lint
pipeline
esm
typer
typescript
completion
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.

cds add sample

This corresponds to the result of the Getting Started in a Nutshell guide.

tiny-sample {.add}

Creates a minimal CAP application without UI.

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:

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

The screenshot is described in the accompanying text. {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 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 instead. :::

Includes and Excludes

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

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

:::

::: 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 like building plugins 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:

Effectively, run:

cf login                   # select the correct org and space here
cf ssh-enabled <app-name>  # 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, which is useful if you can't reduce the number of app instances. :::

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, puts the application in debug mode, and connects and opens the debugger of Chrome DevTools.