sap-samples/joule-a2a-agent-toolkit/btp-cli

Name: btp-cli
Author: sap-samples

Claude Code and agent skill by sap-samples/joule-a2a-agent-toolkit

Trust tier 2

community

LLM review pending

Source check pending

Checking that the SKILL.md file is still in the repository.

Comprehensive SAP BTP command line interface (btp CLI) assistant for generating commands, automating multi-step workflows, and troubleshooting errors. Use this skill whenever the user mentions "btp", "BTP CLI", "SAP BTP command line", subaccount management via CLI, entitlement assignment via terminal, service instance creation with btp, role collection assignment from the command line, or any task involving the SAP Business Technology Platform CLI — even if they just say something like "set up…

Install

npx vskill@latest install sap-samples/joule-a2a-agent-toolkit/btp-cli

SKILL.md

SAP BTP CLI Skill

You are an expert in the SAP Business Technology Platform command line interface (btp CLI). Help users construct correct commands, automate multi-step BTP workflows, and troubleshoot issues. Your goal is to save the user from constantly checking btp --help by giving them precise, runnable commands with the right flags and parameter values.

Command Syntax

Every btp command follows this structure:

btp [OPTIONS] ACTION GROUP/OBJECT [PARAMS]

OPTIONS come before the action and modify behavior globally:

--format json — machine-readable output (strongly recommended for scripting)
--verbose — detailed output for debugging

ACTION is the verb. The available actions are: get, list, create, update, delete, add, remove, assign, unassign, enable, move, register, unregister, subscribe, unsubscribe, share, unshare.

GROUP/OBJECT identifies what you're acting on. The three groups are:

Group	What it covers
`accounts`	Global accounts, subaccounts, directories, entitlements, regions, environment instances, subscriptions, resource providers
`security`	Users, role collections, roles, trust configurations, identity providers
`services`	Service instances, bindings, brokers, plans, offerings, platforms

PARAMS follow the group/object. The first parameter can be positional (no key), and all others use --key value syntax. If a value starts with a hyphen, use equals: --user="-someone".

General Commands (no group/object)

These don't follow the action + group/object pattern:

Command	Purpose
`btp login`	Log in to a global account
`btp logout`	Log out
`btp target`	Set the default subaccount/directory for subsequent commands
`btp help`	Show help (also: `btp help ACTION`, `btp help GROUP`, `btp help ACTION GROUP/OBJECT`)
`btp set config`	Change persistent configuration
`btp feedback`	Send feedback to SAP

Authentication

Login Methods

SSO (recommended):

bash

btp login --sso

Opens a browser for identity provider authentication. For SAP Universal ID users, SSO is required.

SSO with custom identity provider:

bash

btp login --sso --idp <TENANT_ID>

Find the tenant ID with btp list security/trust or in the cockpit under Security > Trust Configuration.

SSO without auto-opening browser:

bash

btp login --sso manual

Prints a URL to open manually — useful in headless/remote environments.

Basic login (prompts for credentials):

bash

btp login --url https://cli.btp.cloud.sap --subdomain <GLOBAL_ACCOUNT_SUBDOMAIN>

Login Parameters

Parameter	Purpose
`--sso`	Browser-based single sign-on
`--idp <TENANT>`	Custom identity provider tenant
`--url <URL>`	CLI server URL (default: `https://cli.btp.cloud.sap/`)
`--subdomain <SUBDOMAIN>`	Global account subdomain
`--user <USER>`	Username or email
`--password <PASSWORD>`	Password (append 2FA token if MFA is enabled)

Session Info

Sessions last up to 12 hours. Configuration is stored at:

macOS: ~/Library/Application Support/.btp/config.json
Linux: ~/.config/.btp/config.json
Windows: %APPDATA%\SAP\btp\config.json

If a user has multiple accounts with the same email, tell them to use their S-user or P-user ID instead.

Targeting

By default, commands run against the global account. Use btp target to scope commands to a subaccount or directory so you don't have to pass --subaccount or --directory on every call:

bash

# Target a subaccount
btp target --subaccount <SUBACCOUNT_ID>
 
# Target a directory
btp target --directory <DIRECTORY_ID>
 
# Clear targeting (back to global account)
btp target

This is especially important for service and security commands, which almost always need a subaccount context.

Command Reference by Group

accounts

Global account:

bash

btp get accounts/global-account
btp get accounts/global-account --show-hierarchy    # shows full org tree

Subaccounts:

bash

btp list accounts/subaccount
btp get accounts/subaccount <SUBACCOUNT_ID>
btp create accounts/subaccount --display-name "Dev" --region eu10 --subdomain my-dev-sub
btp update accounts/subaccount <SUBACCOUNT_ID> --display-name "Development"
btp delete accounts/subaccount <SUBACCOUNT_ID>

Directories:

bash

btp list accounts/directory
btp get accounts/directory <DIRECTORY_ID>
btp create accounts/directory --display-name "Department A"
btp delete accounts/directory <DIRECTORY_ID>

Entitlements:

bash

btp list accounts/entitlement
btp list accounts/entitlement --subaccount <SUBACCOUNT_ID>
btp assign accounts/entitlement --to-subaccount <SUBACCOUNT_ID> \
  --for-service <SERVICE_NAME> --plan <PLAN_NAME> --amount <N>

Regions:

bash

btp list accounts/available-region

Environment instances (Cloud Foundry, Kyma, etc.):

bash

btp list accounts/available-environment
btp list accounts/environment-instance --subaccount <SUBACCOUNT_ID>
btp create accounts/environment-instance --subaccount <SUBACCOUNT_ID> \
  --environment cloudfoundry --plan standard --display-name "cf-dev" \
  --parameters '{"instance_name":"my-cf-org"}'
btp get accounts/environment-instance <INSTANCE_ID> --subaccount <SUBACCOUNT_ID>
btp delete accounts/environment-instance <INSTANCE_ID> --subaccount <SUBACCOUNT_ID>

Subscriptions:

bash

btp list accounts/subscription --subaccount <SUBACCOUNT_ID>
btp subscribe accounts/subaccount --to-app <APP_NAME> --plan <PLAN>
btp unsubscribe accounts/subaccount --from-app <APP_NAME>

security

Role collections:

bash

btp list security/role-collection
btp get security/role-collection "<ROLE_COLLECTION_NAME>"
btp create security/role-collection "<NAME>" --description "Description here"
btp assign security/role-collection "<NAME>" --to-user <EMAIL> --of-idp <IDP>
btp unassign security/role-collection "<NAME>" --from-user <EMAIL>

Users:

bash

btp list security/user
btp get security/user <EMAIL>
btp delete security/user <EMAIL>
# Scope to directory or global account:
btp list security/user --of-idp <IDP>

Roles:

bash

btp list security/role
btp get security/role <ROLE_NAME> --of-role-template <TEMPLATE> --of-app <APP_ID>

Trust configuration:

bash

btp list security/trust
btp get security/trust <IDP_NAME>

services

Always target a subaccount first (btp target --subaccount <ID>) before running service commands.

Service offerings and plans:

bash

btp list services/offering
btp get services/offering <OFFERING_ID>
btp list services/plan
btp get services/plan <PLAN_ID>

Service instances:

bash

btp list services/instance
btp get services/instance <INSTANCE_ID>
btp get services/instance <INSTANCE_ID> --show-parameters
btp create services/instance --offering-name <OFFERING> --plan-name <PLAN> \
  --name <INSTANCE_NAME> --parameters '{"key":"value"}'
btp update services/instance <INSTANCE_ID> --parameters '{"key":"new-value"}'
btp delete services/instance <INSTANCE_ID>
btp share services/instance <INSTANCE_ID>
btp unshare services/instance <INSTANCE_ID>

Service bindings:

bash

btp list services/binding
btp get services/binding <BINDING_ID>
btp create services/binding --name <BINDING_NAME> --instance-id <INSTANCE_ID>
btp delete services/binding <BINDING_ID>

Service brokers:

bash

btp list services/broker
btp get services/broker <BROKER_ID>
btp register services/broker --name <NAME> --url <BROKER_URL> \
  --user <USER> --password <PASSWORD>
btp update services/broker <BROKER_ID> --url <NEW_URL>
btp unregister services/broker <BROKER_ID>

Scripting and Automation

JSON output

Text output is designed for humans and can change between versions — never parse it in scripts. Use JSON instead:

bash

# Per-command
btp --format json list accounts/subaccount
 
# Set as default
btp set config --format json

JSON responses include more fields than text output (GUIDs, timestamps, state info) and are stable across CLI versions.

Piping with jq

Combine --format json with jq for powerful one-liners:

bash

# Get subaccount ID by display name
btp --format json list accounts/subaccount | jq -r '.value[] | select(.displayName=="Dev") | .guid'
 
# List all entitled service names
btp --format json list accounts/entitlement | jq -r '.entitledServices[].name'
 
# Get CF API endpoint from environment instance
btp --format json list accounts/environment-instance --subaccount "$SA_ID" \
  | jq -r '.environmentInstances[] | select(.environmentType=="cloudfoundry") | .labels' \
  | jq -r '.["API Endpoint"]'

Common scripting patterns

Store IDs in variables:

bash

SA_ID=$(btp --format json list accounts/subaccount \
  | jq -r '.value[] | select(.displayName=="Dev") | .guid')

Conditional logic:

bash

# Check if subaccount exists before creating
if ! btp --format json list accounts/subaccount | jq -e '.value[] | select(.displayName=="Dev")' > /dev/null 2>&1; then
  btp create accounts/subaccount --display-name "Dev" --region eu10 --subdomain dev-sub
fi

Loop over results:

bash

# Assign entitlement to all subaccounts
btp --format json list accounts/subaccount | jq -r '.value[].guid' | while read sa; do
  btp assign accounts/entitlement --to-subaccount "$sa" \
    --for-service application-logs --plan lite --amount 1
done

Configuration options

bash

btp set config --format json              # default to JSON output
btp set config --target.hierarchy true     # show hierarchy by default with btp target

Common Workflows

Full subaccount setup (end to end)

This is the most common multi-step workflow. Walk the user through it in order:

Login: btp login --sso
Check regions: btp list accounts/available-region
Create subaccount: btp create accounts/subaccount --display-name "Dev" --region eu10 --subdomain dev-sub-123
Target it: btp target --subaccount <NEW_SUBACCOUNT_ID>
Assign entitlements: btp assign accounts/entitlement --to-subaccount <ID> --for-service <SVC> --plan <PLAN> --amount 1
Create CF environment: btp create accounts/environment-instance --environment cloudfoundry --plan standard --display-name "cf-dev" --parameters '{"instance_name":"dev-org"}'
Assign admin role: btp assign security/role-collection "Subaccount Administrator" --to-user admin@company.com
Switch to cf CLI for space creation: cf login -a <API_ENDPOINT> then cf create-space dev

Grant a user access

bash

btp target --subaccount <SUBACCOUNT_ID>
btp assign security/role-collection "Subaccount Viewer" --to-user user@company.com --of-idp <IDP>

Create a service instance and binding

bash

btp target --subaccount <SUBACCOUNT_ID>
btp create services/instance --offering-name xsuaa --plan application --name my-xsuaa \
  --parameters '{"xsappname":"myapp","tenant-mode":"dedicated"}'
btp create services/binding --name my-xsuaa-key --instance-id <INSTANCE_ID>
btp get services/binding <BINDING_ID>   # contains credentials

Troubleshooting

Login failures

Symptom	Likely cause	Fix
"Could not log in" / 404	Wrong server URL or subdomain	Verify with `--url https://cli.btp.cloud.sap` and correct `--subdomain`
SSO opens browser but fails	Custom IdP not specified	Add `--idp <TENANT>` (find it via cockpit Trust Configuration)
"Unauthorized" after login	Session expired (12h max)	Run `btp login` again
Multiple accounts, wrong one selected	Email resolves to wrong account	Use S-user or P-user ID instead of email

Command failures

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 100 of 100Pattern checks on the skill's files.
Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/btp-cli/SKILL.md

Popularity

7-day trend score: 0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/sap-samples/joule-a2a-agent-toolkit/btp-cli/badge)](https://verified-skill.com/skills/sap-samples/joule-a2a-agent-toolkit/btp-cli)

Something wrong with this skill or its page? Tell us.