btp-cli-reference

# BTP CLI Reference Complete reference for the SAP BTP CLI (`btp`) — session management, full command taxonomy, JSON output patterns, and scope boundaries. Use this skill as a toolset when other skills need to issue BTP CLI commands. ## CLI Version and Architecture ```bash btp --version # Example: SAP BTP command line interface (client v2.x.x) ``` The BTP CLI operates against the **BTP Account API** — it manages the account layer (subaccounts, entitlements, security, service manager). It does NOT manage Cloud Foundry runtime objects (apps, CF service instances, CF spaces) — those require the `cf` CLI. The CLI uses a **session file** stored in `~/.btp/` that caches the login token. A session is valid for a limited time (roughly 12 hours for SSO, longer for some flows). Commands fail silently with "Authorization failed" or "Unknown session" when expired. --- ## Session Management ### Login Methods #### SSO Login (browser-based, recommended for interactive use) ```bash btp login --sso # Opens browser → SAP ID Service login → returns to CLI ``` #### User/Password Login (non-interactive environments) ```bash btp login --user <email> --password <password> # Not recommended for CI/CD — prefer service key + REST APIs ``` #### Custom IDP Login ```bash btp login --sso --idp <custom-idp-origin> # Use when your user is managed by a custom IdP (not SAP ID Service) ``` > **IMPORTANT:** There is NO client-credentials login for the BTP CLI. For headless/automated workflows, use the underlying BTP REST APIs directly with OAuth2 service keys instead. ### Targeting After login, set the default subaccount scope so you don't need `--subaccount` on every command: ```bash btp target --subaccount <subaccount-id> # e.g. btp target --subaccount 2f964175-0856-47b2-b77a-469c74df0cca ``` Check current target: ```bash btp target # Shows: global account, subaccount, org, space ``` Clear target: ```bash btp target --reset ``` ### JSON Output (always use for scripting) ```bash # Set JSON as default for all commands btp set config --format json # Or per-command btp --format json list security/role-collection ``` ### Session Health Check Before running commands in a script, verify the session is active: ```bash btp --format json list accounts/subaccount 2>&1 | grep -q '"subaccounts"' \ && echo "Session OK" || echo "Session expired — run: btp login" ``` ### Gotchas - **Session expires silently** — commands return "Authorization failed. Unknown session." with no hint. Always check first. - **`--subaccount` is optional when targeted** — if you ran `btp target --subaccount <id>`, omit it. If targeting a different subaccount, pass it explicitly. - **`btp` vs `cf`** — BTP CLI manages the account layer; `cf` CLI manages the CF runtime layer. Neither can substitute for the other. - **Interactive-only login** — `btp login` requires a browser or interactive terminal; cannot be used in CI pipelines with stored credentials. Use REST APIs with service keys instead. - **Global account vs. subaccount scope** — some commands apply at global account level (entitlements, provisioning), others at subaccount level (security, services). Use `--global-account` or `--subaccount` to specify. - **`--of-idp` vs `--origin`** — when assigning role collections to users from a custom IdP, use `--of-idp <idp-origin>` (not `--origin`). Example: `btp assign security/role-collection "MyRC" --to-user user@example.com --of-idp sap.default`. - **`btp update security/trust --set-default` does not exist** — setting the default IdP in a CF subaccount must be done manually in BTP Cockpit → Security → Trust Configuration. - **JSON output structure** — top-level key names vary by command. Always inspect output with `jq keys` on first use. - **`--format json` placement** — must come right after `btp`, before the verb: `btp --format json list ...` (not `btp list ... --format json`). --- ## Full Command Taxonomy See [references/command-quick-reference.md](references/command-quick-reference.md) for a single-table quick reference of all 70+ commands. ### Accounts Group Commands for managing the global account, subaccounts, directories, and environment instances. ```bash # Global Account btp get accounts/global-account btp update accounts/global-account --display-name <name> # Subaccounts btp list accounts/subaccount btp get accounts/subaccount <id> btp create accounts/subaccount \ --display-name <name> \ --region <region> \ --subdomain <subdomain> btp update accounts/subaccount <id> --display-name <name> btp delete accounts/subaccount <id> btp move accounts/subaccount <id> --to-directory <dir-id> # Directories btp list accounts/directory btp get accounts/directory <id> btp create accounts/directory --display-name <name> btp update accounts/directory <id> --display-name <name> btp delete accounts/directory <id> btp enable accounts/directory <id> --for entitlements btp enable accounts/directory <id> --for authorizations # Environment Instances (CF Org provisioning) btp list accounts/environment-instance [--subaccount <id>] btp get accounts/environment-instance <id> [--subaccount <id>] btp create accounts/environment-instance \ --environment cloudfoundry \ --service cloudfoundry \ --plan standard \ --subaccount <id> \ --display-name <name> \ --parameters '{"instance_name":"<org-name>"}' btp update accounts/environment-instance <id> \ --subaccount <id> \ --parameters '{"memory":<MB>}' btp delete accounts/environment-instance <id> [--subaccount <id>] # Labels btp list accounts/label [--subaccount <id>] btp set accounts/label --key <key> --value <val> [--subaccount <id>] btp delete accounts/label --key <key> [--subaccount <id>] # Resource providers btp list accounts/resource-provider btp get accounts/resource-provider <provider>/<key> btp create accounts/resource-provider \ --provider <AWS|AZURE|GCP> \ --technical-name <key> btp delete accounts/resource-provider <provider>/<key> # Custom Properties btp list accounts/custom-property [--subaccount <id>] btp set accounts/custom-property --key <key> --value <val> ``` ### Entitlements Group ```bash # List what's available and assigned btp list accounts/entitlement [--subaccount <id>] btp list accounts/entitlement --show-technical-info # Assign entitlement quota to a subaccount btp assign accounts/entitlement \ --service-name <service> \ --plan-name <plan> \ --subaccount <id> \ --amount <N> # For CF Runtime (unlocks memory/routes quota): btp assign accounts/entitlement \ --service-name APPLICATION_RUNTIME \ --plan-name MEMORY \ --subaccount <id> \ --amount <MB> # Assign entitlement to a directory btp assign accounts/entitlement \ --service-name <service> \ --plan-name <plan> \ --directory <id> \ --amount <N> \ --distribute # Subscriptions (SaaS applications) btp list accounts/subscription [--subaccount <id>] btp subscribe accounts/subaccount \ --app-name <app> \ --plan <plan> \ [--subaccount <id>] btp unsubscribe accounts/subaccount \ --app-name <app> \ [--subaccount <id>] ``` ### Security Group Commands for managing roles, role collections, users, and trust. ```bash # Role Collections btp list security/role-collection [--subaccount <id>] btp get security/role-collection "<name>" [--subaccount <id>] btp create security/role-collection "<name>" \ --description "<desc>" \ [--subaccount <id>] btp update security/role-collection "<name>" \ --description "<new-desc>" \ [--subaccount <id>] btp delete security/role-collection "<name>" [--subaccount <id>] # Adding roles to a role collection btp add security/role "<role-name>" \ --to-role-collection "<rc-name>" \ --of-app "<appid>" \ --of-role-template "<template-name>" \ [--subaccount <id>] # Note: <appid> is the XSUAA xsappname!application suffix, e.g. "nonosgi-auth!t12345" # Get it from: btp --format json list security/app | jq '.[] | select(.xsappname=="<appname>") | .appid' # Removing roles from a role collection btp remove security/role "<role-name>" \ --from-role-collection "<rc-name>" \ --of-app "<appid>" \ --of-role-template "<template-name>" \ [--subaccount <id>] # Users btp list security/user [--subaccount <id>] btp get security/user <email> [--of-idp <idp-origin>] [--subaccount <id>] btp create security/user <email> [--of-idp <idp-origin>] [--subaccount <id>] btp delete security/user <email> [--of-idp <idp-origin>] [--subaccount <id>] # Assign/unassign role collections to users btp assign security/role-collection "<rc-name>" \ --to-user <email> \ [--of-idp <idp-origin>] \ [--subaccount <id>] btp unassign security/role-collection "<rc-name>" \ --from-user <email> \ [--of-idp <idp-origin>] \ [--subaccount <id>] # Assign/unassign role collections to user groups btp assign security/role-collection "<rc-name>" \ --to-group <group-name> \ [--of-idp <idp-origin>] \ [--subaccount <id>] # XSUAA Applications (inspect app scopes/roles deployed by MTA) btp list security/app [--subaccount <id>] btp get security/app <appid> [--subaccount <id>] # Lists all scopes and role-templates available from a deployed XSUAA app # Trust Configuration btp list security/trust [--subaccount <id>] btp get security/trust <origin> [--subaccount <id>] btp create security/trust \ --idp <ias-tenant-id-or-host> \ [--subaccount <id>] btp update security/trust <origin> \ --description "<desc>" \ [--subaccount <id>] btp delete security/trust <origin> [--subaccount <id>] btp migrate security/trust "<origin>" [--subaccount <id>] # migrate: convert a SAML trust to OIDC (for IAS tenants only) # Settings btp list security/setting [--subaccount <id>] btp get security/setting <key> [--subaccount <id>] btp set security/setting <key>=<value> [--subaccount <id>] btp unset security/setting <key> [--subaccount <id>] ``` ### Services Group Commands for managing services via Service Manager. ```bash # Service Offerings and Plans btp list services/offering [--subaccount <id>] btp get services/offering <id> [--subaccount <id>] btp list services/plan [--subaccount <id>] btp get services/plan <id> [--subaccount <id>] # Service Instances btp list services/instance [--subaccount <id>] btp get services/instance <id> [--subaccount <id>] btp create services/instance \ --offering-name <svc> \ --plan-name <plan> \ --display-name <name> \ [--parameters '{"key":"value"}'] \ [--subaccount <id>] btp update services/instance <id> \ --display-name <new-name> \ [--parameters '{"key":"value"}'] \ [--subaccount <id>] btp delete services/instance <id> [--subaccount <id>] # Service Bindings (service keys) btp list services/binding [--subaccount <id>] btp get services/binding <id> [--subaccount <id>] btp create services/binding \ --instance-id <instance-id> \ --display-name <binding-name> \ [--parameters '{"key":"value"}'] \ [--subaccount <id>] btp delete services/binding <id> [--subaccount <id>] # Brokers btp list services/broker [--subaccount <id>] btp get services/broker <id> [--subaccount <id>] btp create services/broker \ --name <name> \ --url <url> \ --user <user> \ --password <password> \ [--subaccount <id>] btp update services/broker <id> \ --url <new-url> \ [--subaccount <id>] btp delete services/broker <id> [--subaccount <id>] # Platforms (service manager platforms) btp list services/platform [--subaccount <id>] btp get services/platform <id> [--subaccount <id>] btp register services/platform \ --name <name> \ --type <type> \ [--subaccount <id>]