@sap/datasphere-cli 2023.18.0 → 2023.24.0

package/CHANGELOG.md

@@ -5,6 +5,213 @@ All notable changes to this project SAP Datasphere Command-Line Interface (DS CL
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2023.24.0
+
+### Fixed
+
+- Trailing single quotes (`'`) were removed from option values even though there was no leading single quote. This version contains a fix that trailing single quotes are only removed if there is a leading single quote.
+
+  Trailing single quote is not removed: `some 'value'` stays `some 'value'`.
+
+  Trailing single quote is removed: `'some value'` becomes `some value`.
+
+- The help output did not mention the correct CLI name. Instead the output showed the name 'terminal'.
+
+  ```javascript
+  Usage: terminal [options] [command]
+
+  Command-Line Interface for SAP Datasphere.
+  ...
+  ```
+
+  Since this version, the name is shown correctly.
+
+  ```javascript
+  Usage: datasphere [options] [command]
+
+  Command-Line Interface for SAP Datasphere.
+  ...
+  ```
+
+## 2023.19.0
+
+### Added
+
+- Support for managing multiple logins/secrets for different tenants in parallel. The `datasphere login` and `datasphere logout` commands have been updated, allowing you to login to multiple tenants in parallel. When running a command, the CLI uses the secret matching the currently maintained tenant URL via the `-H, --host` option or set via `datasphere config host set <host>`. You now must specify the host which you are logging in to using option `-H, --host`, or by setting the host globally first by calling `datasphere config host set <host>`, to allow the CLI to store the secret for the defined tenant URL.
+
+  You can list all locally stored secrets by running `datasphere config secrets show`.
+
+  ```javascript
+  $ datasphere config secrets show
+  [
+    {
+      "id": 0,
+      "client_id": "sb-0d85e619...",
+      "client_secret": "1dcc0522-...",
+      "tenantUrl": "https://somehost.eu10.cloud.sap",
+      ...
+    },
+    {
+      "id": 1,
+      "client_id": "sb-0d85e619...",
+      "client_secret": "1dcc0522-...",
+      "tenantUrl": "https://somehost.us10.cloud.sap",
+      ...
+    }
+  ]
+  ```
+
+  In order to logout again, the `datasphere logout` command allows you to optionally specify the ID of the login/secret to remove using option `-l, --login-id <id>`.
+
+  ```javascript
+  datasphere logout --help
+  Usage: datasphere logout [options]
+
+  log out from your account
+
+  Options:
+    -l, --login-id <id>  specifies the login ID (optional) (choices: "0", default: "0")
+    -h, --help           display help for command
+  ```
+
+  By default, when you omit option `-l, --login-id <id>`, the login/secret with ID _0_ is removed.
+
+  You cannot login to the same tenant with different _access tokens_ at the same time. There can only be a single login/secret per tenant, but you can login into multiple tenants in parallel. If you need to login with different users into the same tenant, you have to logout first, then login again with a different user.
+
+- Support for predefined OAuth clients where the client ID _does not_ start with the term `sb-`. When using a predefined OAuth client where the client ID _does not_ start with the term `sb-`, the CLI uses a different default port `65000` to retrieve the temporary code to retrieve the access token and refresh token. The port can be changed using the environment variable mentioned in the [README.md](README.md) file.
+
+- Improved OAuth authorization URL and token URL support. You do not have to specify the options for the _OAuth Client Authorization URL_ and _Token URL_ anymore, if you specify the tenant URL using the _-H, --host_ option. The CLI calculates the required authorization and token URLs automatically based on the given _Client ID_, _Client Secret_, and _Tenant URL_. You can still use the respective options to provide values for the authorization URL and token URL to override the calculated values.
+
+### Changed
+
+- Generic options are hidden for all commands. Before, all options where shown, including generic options applicable to any command.
+
+  ```bash
+  $ datasphere spaces read --help
+  Usage: datasphere spaces read [options]
+  fetch space details for a specified space
+  Options:
+    -V, --verbose                    print detailed log information to console (optional)
+    -O, --options-file <file>        path to options file (optional)
+    -H, --host <host>                specifies the url where the tenant is hosted (optional)
+    -c, --client-id <id>             client id for interactive oauth session authentication (optional)
+    -C, --client-secret <secret>     client secret for interactive oauth session authentication (optional)
+    -a, --access-token <token>       access token for interactive oauth session authentication (optional)
+    -r, --refresh-token <token>      refresh token for interactive oauth session authentication (optional)
+    -b, --code <code>                code for oauth token retrieval (optional)
+    -t, --token-url <url>            token url for interactive oauth session authentication (optional)
+    -A, --authorization-url <url>    authorization url for interactive oauth session authentication (optional)
+    -p, --passcode <passcode>        passcode for interactive session authentication (optional)
+    -s, --secrets-file <file>        path to secrets file (optional)
+    -e, --expires-in <expires>       expires in information for interactive oauth session authentication (optional)
+    -o, --output <output>            specifies the file to store the output of the command (optional)
+    -P, --pretty                     pretty-formats JSON responses (optional)
+    -S, --space <space>              space ID (optional)
+    -N, --no-space-definition        do not read space definition (optional)
+    -m, --definitions [definitions]  read definitions (optional)
+    -q, --connections [connections]  read connections (optional)
+    -h, --help                       display help for command
+  ```
+
+  Now, only command-specific options are shown.
+
+  ```bash
+  $ datasphere spaces read --help
+  Usage: datasphere spaces read [options]
+  fetch space details for a specified space
+  Options:
+  -S, --space <space> space ID (optional)
+  -N, --no-space-definition do not read space definition (optional)
+  -m, --definitions [definitions] read definitions (optional)
+  -q, --connections [connections] read connections (optional)
+  -h, --help display help for command
+  Only command-specific options are listed here. To learn more about available generic options, visit https://your.generic.options.help.url
+  ```
+
+- Option `-P, --pretty` changes to `-n, --no-pretty`. You can now supply option `-n, --no-pretty` to not pretty-format the response of a command. By default, the response of a command is pretty-formatted. When adding the option `-h, --help` to any command, the help tells you about the possible uses.
+
+  ```bash
+  $ datasphere spaces read --help
+  Usage: datasphere spaces read [options]
+
+  fetch space details for a specified space
+
+  Options:
+    -n, --no-pretty       do not pretty-format JSON responses (optional)
+    -h, --help            display help for command
+  ```
+
+  When calling a command that supports the `-P, --pretty` option you can explicitly specify to pretty-print the result.
+
+  `$ datasphere spaces read --pretty true`
+
+  To disable pretty-printing, set `-P, --pretty` to `false`.
+
+  `$ datasphere spaces read --pretty false`
+
+  Calling a command without specifying the `-P, --pretty` option explicitly yields the same output as when calling the command with `--pretty true`.
+
+- A new top-level command `config` has been introduced. This command groups all the CLI configuration-related commands such as `cache`, `secrets`, `host`, ...
+
+  **Old Structure**
+
+  ```bash
+  $ datasphere
+  Usage: datasphere [options] [command]
+
+  Command-Line Interface for SAP Datasphere.
+
+  Options:
+    -v, --version              output the current version
+    -H, --host <host>          specifies the url where the tenant is hosted (optional)
+    -O, --options-file <file>  path to options file (optional)
+    -h, --help                 display help for command
+
+  Commands:
+    cache                      work with the local CLI cache
+    dbusers [options]          manage and orchestrate database users
+    help [command]             display help for command
+    host                       configure host properties
+    login [options]            log in to your account using interactive OAuth authentication
+    logout                     log out from your account
+    marketplace [options]      manage and orchestrate your SAP Data Marketplace
+    passcode-url [options]     display the passcode url
+    secrets                    work with the locally stored secrets
+    spaces [options]           manage and orchestrate spaces
+    tasks [options]            manage tasks
+  ```
+
+  **New Structure**
+
+  ```bash
+  $ datasphere
+  Usage: datasphere [options] [command]
+
+  Command-Line Interface for SAP Datasphere.
+
+  Options:
+    -v, --version              output the current version
+    -H, --host <host>          specifies the url where the tenant is hosted (optional)
+    -O, --options-file <file>  path to options file (optional)
+    -h, --help                 display help for command
+
+  Commands:
+    config                     configure your CLI
+    dbusers [options]          manage and orchestrate database users
+    help [command]             display help for command
+    login [options]            log in to your account using interactive OAuth authentication
+    logout                     log out from your account
+    marketplace [options]      manage and orchestrate your SAP Data Marketplace
+    spaces [options]           manage and orchestrate spaces
+    tasks [options]            manage tasks
+  ```
+
+- The environment variable `DWC_CLI_PORT` changed to `CLI_HTTP_PORT`.
+
+### Fixed
+
+- Values entered for the _Authorization URL_ and _Token URL_ could be entered including query parameters like `https://some.authorization.url?some.parameter=some.value`. The CLI did not remove the query parameters when using the URLs to retrieve the temporary code. This has been changed, the query parameters are now removed. The CLI changes an URL from `https://some.authorization.url?some.parameter=some.value` to `https://some.authorization.url` to retrieve the temporary code.
+
 ## 2023.10.0
 
 Package `@sap/datasphere-cli` was released.

package/README.md

@@ -100,13 +100,13 @@ $ datasphere secrets show
 If you do not want to log in and have the CLI store the secrets in the CLI cache locally, you can also provide the _access_token_ directly on the command line:
 
 ```bash
-$ datasphere cache init --host <my host> --access-token <access token>
+$ datasphere config cache init --host <my host> --access-token <access token>
 ```
 
 Alternatively, you can provide the _access_token_ through a `secrets.json` file:
 
 ```bash
-$ datasphere cache init --host <my host> -secrets-file /path/to/secrets.json
+$ datasphere config cache init --host <my host> -secrets-file /path/to/secrets.json
 ```
 
 The `secrets.json` file must at least contain a property called `access_token`:
@@ -126,7 +126,7 @@ Passcodes are used for authenticating commands sent from the CLI to your SAP Dat
 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.
 
 ```bash
-$ datasphere cache init -H https://mytenant.eu10.hcs.cloud.sap/
+$ datasphere config 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: … **********
 ...
@@ -152,16 +152,16 @@ You can either use the CLI from the terminal or command line, or use the module
 Before you can list and run commands against your SAP Datasphere tenant you need to initialize the CLI first. When initializing the CLI a service document is downloaded from your SAP Datasphere tenant which describes the commands your tenant is able to understand. To initialize the CLI run
 
 ```bash
-$ datasphere cache init -H https://mytenant.eu10.hcs.cloud.sap/ -p somepasscode
+$ datasphere config 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.
+You can refresh the local copy of the service document by running the `config 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.
+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 `config cache init` command again.
 
 ```bash
 $ datasphere <command>
-Your local CLI cache is outdated. Run 'datasphere cache init' to update
+Your local CLI cache is outdated. Run 'datasphere config cache init' to update
 ```
 
 #### List available commands
@@ -181,7 +181,7 @@ Options:
 
 Commands:
   cache clean             clean the local CLI cache
-  cache init [options]    initialize the local CLI cache
+  config cache init [options]    initialize the local CLI cache
   passcode-url [options]  print the passcode url
   help [command]          display help for command
 ```
@@ -201,7 +201,7 @@ Options:
 
 Commands:
   cache clean             clean the local CLI cache
-  cache init [options]    initialize the local CLI cache
+  config 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
@@ -240,7 +240,7 @@ Options:
   -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`.
+The list of available commands differs based on the content of the service document you downloaded when running `config cache init`.
 
 ### As a Node.js module dependency
 
@@ -252,7 +252,7 @@ const datasphere = require("@sap/datasphere-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`, ...
+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`, `config cache init`, ...
 
 ```javascript
 const MY_HOST = "https://mytenant.eu10.hcs.cloud.sap/";
@@ -263,7 +263,7 @@ console.log(commands);
 // {
 //   datasphere: [AsyncFunction],
 //   'cache clean': [AsyncFunction],
-//   'cache init': [AsyncFunction],
+//   'config cache init': [AsyncFunction],
 //   'passcode-url': [AsyncFunction],
 //   'cache show': [AsyncFunction]
 //   'spaces create': [AsyncFunction]
@@ -282,7 +282,7 @@ const options = {
   "--passcode": "somepasscode",
 };
 
-await commands["cache init"](options);
+await commands["config 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.
@@ -383,9 +383,9 @@ await commands["spaces read"]({
 No matter how you use the CLI ([from the command-line](#from-the-command-line) or [as a Node.js module dependency](#as-a-nodejs-module-dependency)), you can supply values for options in different ways. To get an overview of the existing options per command, run `datasphere <command> --help`:
 
 ```bash
-$ datasphere cache init --help
+$ datasphere config cache init --help
 
-Usage: datasphere cache init [options]
+Usage: datasphere config cache init [options]
 
 initialize the local CLI cache
 
@@ -410,7 +410,7 @@ Options:
 You can use the short flag or long name to supply an option value on the command-line:
 
 ```bash
-$ datasphere cache init --host <host>
+$ datasphere config cache init --host <host>
 ```
 
 #### Using environment variables
@@ -418,7 +418,7 @@ $ datasphere cache init --host <host>
 To provide an option value, the option's long name is translated to CONSTANT_CASE. For example, the option `client-id` can also be provided as follows:
 
 ```bash
-$ CLIENT_ID='<my client id>' HOST='my-host' datasphere cache init
+$ CLIENT_ID='<my client id>' HOST='my-host' datasphere config cache init
 ```
 
 #### Provide options file
@@ -437,14 +437,14 @@ You can provide a JSON file with a map of options, using the option's long names
 Then, supply it to the CLI:
 
 ```bash
-$ datasphere cache init --options-file /path/to/options-file.json
+$ datasphere config cache init --options-file /path/to/options-file.json
 ```
 
 ### Environment Variables
 
 The CLI supports the following environment variables. You can set the environment variables when calling the CLI according to the local environment. In addition, the CLI supports the [`dotenv`](https://www.npmjs.com/package/dotenv#usage) module, allowing you to place a `.env` file in the CLI working directory.
 
-#### `DWC_CLI_PORT`
+#### `CLI_HTTP_PORT`
 
 Defines the port the CLI starts the HTTP server at when logging in when using OAuth clients for authentication.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sap/datasphere-cli",
-  "version": "2023.18.0",
+  "version": "2023.24.0",
   "description": "Command-Line Interface for SAP Datasphere.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "SAP SE",
@@ -19,6 +19,6 @@
     "datasphere-cli"
   ],
   "dependencies": {
-    "@sap/cli-core": "2023.17.0"
+    "@sap/cli-core": "2023.23.0"
   }
 }

package/utils.js

@@ -10,6 +10,7 @@ const configure = () => {
         description: (0, cli_core_1.getDescription)(__dirname),
         sapHelpLink: "tinyurl.com/datasphere-cli-help",
         version: (0, cli_core_1.getVersion)(__dirname),
+        genericOptionsHelp: "https://tinyurl.com/yck8vv4w",
         authenticationMethods: [
             cli_core_1.AuthenticationMethod.oauth,
             cli_core_1.AuthenticationMethod.passcode,