simplemdg-dev-cli 1.4.0 → 1.4.1

package/USER_GUIDE.md

@@ -1,229 +1,283 @@
-# SimpleMDG Dev CLI
+# SimpleMDG Dev CLI Guide
 
-SimpleMDG Dev CLI helps developers prepare local repositories, connect to SAP BTP Cloud Foundry, run CAP services, export metadata, view logs, and debug deployed apps with fewer manual commands.
+## Purpose
 
-## Install
+`simplemdg-dev-cli` helps SimpleMDG developers run common local development and BTP tasks without remembering long commands.
 
-```powershell
-npm i -g simplemdg-dev-cli@latest
-```
-
-Check installation:
+Main command:
 
-```powershell
-smdg --help
+```bash
+smdg
 ```
 
-You can also use:
+Install:
 
-```powershell
-simplemdg --help
+```bash
+npm i -g simplemdg-dev-cli@latest
 ```
 
-## Interactive guide
-
-Run:
+Open this guide:
 
-```powershell
-smdg --help
+```bash
+smdg guide
 ```
 
-You can choose one of these options:
-
-- View quick guide in terminal
-- Open visual guide in browser
-- Show command help
+---
 
-You can also open the guide directly:
+# Select Usage
 
-```powershell
-smdg guide
-```
+When the CLI shows a select list:
 
-Open visual local guide:
+* Type a few characters to search.
+* Use `↑` and `↓` to move.
+* Press `Enter` to select.
+* If no item matches, some prompts allow using the typed value.
 
-```powershell
-smdg guide --web
-```
+This is useful for long lists of BTP orgs, spaces, apps, package IDs, CAP profiles, and CDS services.
 
-Print guide in terminal:
+---
 
-```powershell
-smdg guide --terminal
-```
+# Common Commands
 
-## Common usage
+## `smdg npmrc import`
 
-### Create `.npmrc`
+Import SimpleMDG GitLab package IDs into local cache.
 
-Import SimpleMDG GitLab package IDs first:
+Use this after downloading the package ID import file from the team.
 
-```powershell
-smdg npmrc import --file simplemdg-package-ids-import.txt
+```bash
+smdg npmrc import
 ```
 
-Create `.npmrc`:
+## `smdg npmrc create`
+
+Create `.npmrc` for SimpleMDG private npm packages.
 
-```powershell
+```bash
 smdg npmrc create
 ```
 
-The CLI caches package IDs with names, scopes, GitLab hosts, and tokens, so you can select them quickly next time.
+The CLI helps select package name/package ID and token from cache.
 
-### Install project dependencies
+## `smdg i`
 
-```powershell
+Install dependencies for the current project.
+
+```bash
 smdg i
 ```
 
-This scans placeholders like `${SIMPLEMDG_BRANCH}` and asks for replacement values before running install. It helps avoid manually replacing values in `package.json`.
-
-Full command:
+It can scan variables such as `${SIMPLEMDG_BRANCH}` and ask for replacement values automatically.
 
-```powershell
-smdg install
-```
+## `smdg cf login`
 
-### Login to BTP / Cloud Foundry
+Login to BTP Cloud Foundry.
 
-```powershell
+```bash
 smdg cf login
 ```
 
-The CLI asks for the CF API endpoint, username, and password. Then it scans available orgs and spaces based on your account permission.
+The CLI helps select API endpoint, org, and space. Choose to save the password on your own machine if you want automatic re-login for org switching, logs, app listing, and debugging.
+
+It can save login information on your local machine so later commands can re-login automatically when the CF session expires.
+
+## `smdg cf org`
 
-### Switch org across regions
+Search, list, and switch Cloud Foundry orgs across regions.
 
-```powershell
+```bash
 smdg cf org
 ```
 
-Use this when you already logged in and only want to list or switch org/space. The org list shows both region and org name.
+The CLI scans known and cached BTP region endpoints and shows orgs from different regions in one searchable list. If the CF session for a region is expired, the CLI automatically re-authenticates by using the username/password saved from `smdg cf login`.
 
-### Check current target
+The list includes region information, for example:
+
+```txt
+arthrex-dev-simplemdg    eu10 · 1 space
+alcon-dev-simplemdg      br10 · 1 space
+ait-dev-simplemdg        us21 · 1 space
+```
 
-```powershell
+Use this when you have many orgs across many BTP regions. Run `smdg cf login` once and choose to save the password on your machine so org switching, app listing, logs, and debug can re-login automatically when the CF session expires.
+
+## `smdg cf target`
+
+Show the current Cloud Foundry target.
+
+```bash
 smdg cf target
 ```
 
-### List BTP apps
+It shows API endpoint, user, org, and space.
+
+## `smdg cf apps`
+
+List BTP apps in the current org and space.
 
-```powershell
+```bash
 smdg cf apps
 ```
 
-This shows cached apps immediately and refreshes the cache in the background.
+The CLI uses cache first for speed and refreshes in the background.
 
-Force refresh:
+## `smdg cf bind`
 
-```powershell
-smdg cf apps --refresh
+Bind the local CAP project to a deployed BTP app service.
+
+```bash
+smdg cf bind
 ```
 
-### Bind local CAP service to BTP app services
+This helps run `cds bind --to-app-services` and update `.cdsrc-private.json`.
 
-```powershell
-smdg cf bind
+## `smdg cf env`
+
+Export BTP app environment variables to a clean JSON file.
+
+```bash
+smdg cf env
 ```
 
-The CLI lets you select a BTP app and runs:
+Useful for creating `default-env.json`.
+
+## `smdg cds watch`
+
+Run CAP locally.
 
-```powershell
-cds bind --to-app-services <app-name>
+```bash
+smdg cds watch
 ```
 
-### Export BTP env to clean JSON
+The CLI helps select CAP profile and port.
 
-```powershell
-smdg cf env
+## `smdg cf logs`
+
+View BTP app logs.
+
+```bash
+smdg cf logs
 ```
 
-Or write directly to `default-env.json`:
+It can be used for realtime log monitoring.
+
+## `smdg cf debug`
 
-```powershell
-smdg cf env --out default-env.json
+Debug a deployed BTP Cloud Foundry Node.js app.
+
+```bash
+smdg cf debug
 ```
 
-Export raw CF output for debugging:
+The CLI guides you through:
+
+* selecting current target or searching orgs across regions
+* selecting BTP app
+* selecting debug mode
+* selecting app instance
+* preparing Node.js inspector
+* creating VS Code attach config
+* opening the CF SSH tunnel
 
-```powershell
-smdg cf env --raw --out default-envBTP.raw.txt
+Recommended mode:
+
+```txt
+VS Code guided debugging
 ```
 
-### Run CAP watch
+Important VS Code note:
 
-```powershell
-smdg cds watch
+The debug toolbar buttons such as pause, step over, restart, and stop only appear after VS Code successfully attaches to the running Node.js inspector.
+
+Normal flow:
+
+1. Run `smdg cf debug`.
+2. Select `VS Code guided debugging`.
+3. First time for an app, select `Set NODE_OPTIONS and restart app`.
+4. Keep the terminal open because it owns the CF SSH tunnel.
+5. In VS Code, open Run and Debug with `Ctrl+Shift+D`.
+6. Select `Attach BTP <app-name>`.
+7. Press `F5` or the green Start Debugging button.
+8. After attach succeeds, the debug toolbar appears.
+
+Use this mainly in dev/test environments because enabling Node inspector restarts the BTP app.
+
+## `smdg cds compline`
+
+Generate metadata XML from CDS services.
+
+```bash
+smdg cds compline
 ```
 
-The CLI scans CAP profiles and asks for a port.
+The CLI scans CDS services, suggests output XML names, and writes XML using UTF-8 encoding.
+
+---
 
-Quick command:
+# Recommended Daily Flow
 
-```powershell
-smdg cds watch --profile hybrid --port 4005
+```bash
+smdg npmrc create
+smdg i
+smdg cf login
+smdg cf apps
+smdg cf bind
+smdg cf env
+smdg cds watch
 ```
 
-### View BTP logs realtime
+For logs:
 
-```powershell
+```bash
 smdg cf logs
 ```
 
-Export recent logs:
+For BTP debugging:
 
-```powershell
-smdg cf logs --recent --out logs/app.log
+```bash
+smdg cf debug
 ```
 
-### Export CAP metadata XML
+For metadata XML:
 
-```powershell
+```bash
 smdg cds compline
 ```
 
-Default output format is `edmx`. The CLI scans CAP services, suggests output XML names, and writes files using UTF-8 encoding.
+---
 
-Quick command:
+# Key Features
 
-```powershell
-smdg cds compline --to edmx --service MainService --out srv_config_main.xml
-```
+## Private npm registry helper
 
-### Debug BTP app
+Creates `.npmrc` for SimpleMDG GitLab npm packages and caches package IDs with readable names.
 
-```powershell
-smdg cf debug
-```
+## Smart install helper
 
-The CLI asks you to select:
+Scans project variables like `${SIMPLEMDG_BRANCH}` and asks for values automatically before install.
 
-- org/space mode
-- BTP app
-- debug mode
-- app instance
-- local debug port
+## Cloud Foundry helper
 
-It can generate VS Code attach config, open a CF SSH tunnel, print Chrome DevTools links, or check/enable SSH.
+Helps with login, target checking, org switching, app list, binding, env export, logs, and debugging.
 
-## How to use CLI select screens
+## Across-region org search
 
-When the CLI shows a select list:
+Scans known and cached BTP regions and shows orgs from many regions in one searchable list. The CLI now re-authenticates per region using the cached login profile, so switching orgs should not fail just because `cf api` changed to another region.
 
-- Type a few characters to search.
-- Use `↑` and `↓` to move.
-- Press `Enter` to select.
-- If no item matches, press `Enter` to use the value you typed.
+## CAP helper
 
-## Recommended local service flow
+Helps run `cds watch`, select profiles/ports, and generate CDS metadata XML.
 
-```powershell
-smdg npmrc create
-smdg i
-smdg cf login
-smdg cf target
-smdg cf apps
-smdg cf bind
-smdg cf env --out default-env.json
-smdg cds watch --profile hybrid --port 4005
-```
+## VS Code BTP debugging
+
+Creates VS Code attach config and opens a CF SSH tunnel to debug BTP Node.js apps from local source code. For the first debug session of an app, use `Set NODE_OPTIONS and restart app`; later sessions can use `Inspector is already enabled`.
+
+---
+
+# Notes
+
+Do not commit real secrets to Git.
+
+Files like `.npmrc`, `default-env.json`, and cached passwords may contain sensitive data.
+
+Use saved password only on your own machine.