Noosphere Possibilities Maximized

    @sap/dwc-cli
    TypeScript icon, indicating that this package has built-in type declarations

    2022.11.1 • Public • Published

    @sap/dwc-cli

    Command-Line Interface (CLI) for SAP Data Warehouse Cloud.

    Content

    1. Installation
    2. Update the CLI
    3. Versioning
    4. Authentication
    5. Usage
      1. From the command line
      2. As a Node.js module dependency
    6. Help & Documentation
    7. Community & Feedback
    8. License
    9. Release Notes

    Installation

    $ npm install -g @sap/dwc-cli

    or

    $ yarn global add @sap/dwc-cli

    Update the CLI

    See Installation.

    In case of structural changes applied to the service document (see Initialize the CLI) with a new version of Data Warehouse Cloud you need to update the CLI. In this case, after you executed a command, the CLI issues a warning:

    $ dwc <command>
    Your local CLI installation is outdated. Run 'npm install @sap/dwc-cli [-g]' to update

    Versioning

    The semantic versioning of the CLI is handled according to SAP Data Warehouse Cloud versions and follows the same structure for major and minor versions.

    $ dwc -v
    2021.21.0

    For an in-depth explanation see the blog post on blogs.sap.com.

    Authentication

    Passcodes are used for authenticating commands sent from the CLI to your SAP Data Warehouse Cloud tenant. Passcodes can be provided explicitly using the -p, --passcode option in case the URL to retrieve a passcode is known, or implictly using an interactive session by omitting the -p, --passcode option.

    When omitting the -p, --passcode option the CLI prompts you to provide a passcode by navigating to the passcode authentication URL for your tenant. The URL is calculated based on the provided -H, --host value.

    $ dwc cache-init -H https://mytenant.eu10.hcs.cloud.sap/
    ✔ Do you want to retrieve a passcode from https://mytenant.authentication.eu10.hana.ondemand.com/passcode? … yes
    ✔ Enter your temporary authentication code: … **********
    ...

    The displayed URL can be used for retrieving more passcodes by refreshing the page when sending multiple commands which can then be fed to the -p, --passcode option.

    You can retrieve the URL directly by running the passcode-url command:

    $ dwc passcode-url -H https://mytenant.eu10.hcs.cloud.sap/
    https://mytenant.authentication.eu10.hana.ondemand.com/passcode

    Usage

    You can either use the CLI from the terminal or command line, or use the module as a regular dependency in your code of your Node.js project.

    From the command line

    Initialize the CLI

    Before you can list and run commands against your SAP Data Warehouse Cloud tenant you need to initialize the CLI first. When initializing the CLI a service document is downloaded from your SAP Data Warehouse Cloud tenant which describes the commands your tenant is able to understand. To initialize the CLI run

    $ dwc cache-init -H https://mytenant.eu10.hcs.cloud.sap/ -p somepasscode

    You can refresh the local copy of the service document by running the cache-init command again.

    After you executed a command the CLI issues a warning in case the local version of the service document is outdated. In that case, run the cache-init command again.

    $ dwc <command>
    Your local CLI cache is outdated. Run 'dwc cache-init' to update

    List available commands

    To list available commands and required or optional options attach the -h, --help to the top-level dwc command or any subcommand of dwc:

    $ dwc -h
    Usage: dwc [options] [command]
    
    Command-Line Interface for SAP Data Warehouse Cloud.
    
    Options:
      -v, --version           output the current version
      -H, --host <host>       specifies the url host where the tenant is hosted
      -h, --help              display help for command
    
    Commands:
      cache-clean             clean the local CLI cache
      cache-init [options]    initialize the local CLI cache
      passcode-url [options]  print the passcode url
      help [command]          display help for command

    To list commands for a tenant for which the CLI was initialized, add the -H, --host option (notice the additional command spaces):

    $ dwc -H https://mytenant.eu10.hcs.cloud.sap/ -h
    Usage: dwc [options] [command]
    
    Command-Line Interface for SAP Data Warehouse Cloud.
    
    Options:
      -v, --version           output the current version
      -H, --host <host>       specifies the url host where the tenant is hosted
      -h, --help              display help for command
    
    Commands:
      cache-clean             clean the local CLI cache
      cache-init [options]    initialize the local CLI cache
      spaces                  manage and orchestrate spaces
      passcode-url [options]  print the passcode url
      help [command]          display help for command

    To show available subcommands for a top-level command, run eg:

    $ dwc spaces -H https://mytenant.eu10.hcs.cloud.sap/ -h
    Usage: dwc spaces [options] [command]
    
    manage and orchestrate spaces
    
    Options:
      -H, --host <host> specifies the url host where the tenant is hosted
      -h, --help        display help for command
    
    Commands:
      create [options]  creates or updates space details based on an import file
      read [options]    fetches space details for a specified space
      delete [options]  delete an existing space
      help [command]    display help for command
    $ dwc spaces create -H https://mytenant.eu10.hcs.cloud.sap/ -h
    Usage: dwc spaces create [options]
    
    creates or updates space details based on an import file
    
    Options:
      -f, --filePath <filePath>  specifies the file to use as input for the command
      -V, --verbose              print detailed log information to console (optional)
      -H, --host <host>          specifies the url host where the tenant is hosted
      -p, --passcode <passcode>  passcode for interactive session authentication (optional)
      -h, --help                 display help for command

    The list of available commands differs based on the content of the service document you downloaded when running cache-init.

    As a Node.js module dependency

    Require the module as usual. You can also use it in your TypeScript project using the import syntax.

    const dwc = require("@sap/dwc-cli");

    Work with commands

    The module exports a getCommands function which returns a map of available commands. Make sure to always specify the host to receive host-specific commands. Otherwise, when omitting the host information, you will only get the list of general commands like cache-clean, cache-init, ...

    const MY_HOST = "https://mytenant.eu10.hcs.cloud.sap/";
    
    const commands = await dwc.getCommands(MY_HOST);
    
    console.log(commands);
    // {
    //   dwc: [AsyncFunction],
    //   'cache-clean': [AsyncFunction],
    //   'cache-init': [AsyncFunction],
    //   'passcode-url': [AsyncFunction],
    //   'cache-show': [AsyncFunction]
    //   'spaces create': [AsyncFunction]
    //   'spaces read': [AsyncFunction]
    //   'spaces delete': [AsyncFunction]
    // }

    You can call any available command and provide required options as follows:

    const MY_HOST = "https://mytenant.eu10.hcs.cloud.sap/";
    
    const options = {
      "--host": MY_HOST,
      "--passcode": "somepasscode",
    };
    
    await commands["cache-init"](options);

    options is a map of available options for the respective command. You have to supply either the short flag or long name of the option, including - or -- for the short flag or long name.

    Handle errors during command execution

    If the command fails, an error is thrown you can catch and process as usual:

    try {
      await commands["cache-show"]();
    } catch (err) {
      // ops, the command failed!
      console.log(err);
    }

    Provide custom logger function

    Any output of a command you execute is forwarded to the logger.output function. To handle the result yourself, you can provide a custom logger.output function implementation:

    let result = [];
    const output = (...args) => result.push(args);
    dwc.configure({ customLogger: { output } });
    
    await commands["spaces read"]({
      "--space": "MYSPACE",
      "--host": "https://mytenant.eu10.hcs.cloud.sap/",
      "--passcode": "mypasscode",
    });
    
    console.log(result);
    // [
    //   [
    //     '{\n' +
    //       '  "MYSPACE": {\n' +
    //       '    "spaceDefinition": {\n' +
    //       '      "version": "1.0.4",\n' +
    // ...
    //       '    }\n' +
    //       '  }\n' +
    //       '}'
    //   ]
    // ]

    Provide custom passcode retrieval function

    You can also provide a custom passcode retrieval function which is called every time before a command is executed. The function is expected to return a promise resolving into a string, the passcode. This way you can, for example, make use of programmatic passcode retrieval as described in this blog using a headless browser and can omit the --passcode option when executing commands. The function needs to be configured only once before executing the first command.

    const customLogger = {
      customLogger: { output: console.log },
    };
    
    const passcodeFunction = () => {
      // instantiate headless browser, retrieve passcode, return it
    };
    
    dwc.configure(logger, passcodeFunction);
    
    // no --passcode option required
    await commands["spaces read"]({
      "--space": "MYSPACE",
      "--host": "https://mytenant.eu10.hcs.cloud.sap/",
    });

    Help Documentation

    Find the full documentation on help.sap.com, check out the blog post on blogs.sap.com or use option -h, --help:

    $ dwc <command> -h

    Community & Feedback

    SAP Community provides a forum where you can ask and answer questions, and comment and vote on the questions of others and their answers.

    See SAP Data Warehouse Cloud community for more details and use the tag dwc-cli for questions concerning the CLI.

    License

    This package is provided under the terms of the SAP Freeware License Agreement.

    Release Notes

    Find all information about changes, enhancements, differents to previous versions and bug fixes here.

    Version 2022.9.1

    • Fixed local cache issue: After initializing the CLI using cache-init, no additional commands like spaces was available. The downloaded discovery document for the tenant in question was effectively ignored.

    Version 2022.9.0

    • Respect HTTP protocol of tenant entered by user: No matter what the protocol of the tenant (https or http), the HTTP request send to the backend service of the respective tenant was always using https. This can cause issues if the client using the CLI is hidden behind a HTTP proxy which only allows for http requests. This addresses cases where commands failed with errors like "self signed certificate in certificate chain".
    • The CLI could not be used as a regular Node.js dependency using the requires or import syntax within a Node.js project. Users of the CLI always had to use Node.js' exec functionality to work with the CLI. For more information, see Using the CLI from the command line.

    Install

    npm i @sap/dwc-cli

    Homepage

    www.sap.com

    DownloadsWeekly Downloads

    85

    Version

    2022.11.1

    License

    SEE LICENSE IN LICENSE

    Unpacked Size

    141 kB

    Total Files

    106

    Last publish

    Collaborators

    • sap_extncrepos