BT-CLI demo flow — working commands

Verified live against tenant pf922288, 01 Jul 2026. Real IDs baked in. Ephemeral IDs (request/session) are captured at runtime, not hardcoded.

tag = docs bucket (BT-CLI / API) VERIFIED — ran live, non-destructive, safe to demo STATE-CHANGING — correct syntax, changes/creates/deletes; run deliberately

Real values (pf922288)
system ad.upm.academy .......... ID 19 (Active Directory)
system linhost2 ................ ID 6 (Linux — used for the create demo)
account svc_app ................. ID 18119 (exists; credential test PASSED)
safe GitHub - BTSolution-Engineering ... 9b56a95b-0a8a-4be6-de3c-08dd5118ea68
folder IaC-Demo ............... bec2694b-994a-47cd-07c2-08de5e7a5e2d
group SecretsSafe_Access ..... ID 9 (Dev_Ansible=10, API_Users=11)
secret path ................... GitHub - BTSolution-Engineering/IaC-Demo/AWS
perm flags ..................... None, Read, Create, Edit, Delete, Share, Manage

Setup — run once per session

Session setupVERIFIED

source .venv/bin/activate

bt whoami

Credentials load from ~/.bt-cli/config.yaml — no source .env needed. bt whoami should show Password Safe = Connected (user NH-Ansible, ID 120).

Show the underlying REST call (demo toggle)APIVERIFIED

bt --show-rest pws accounts get 18119

Prepend bt --show-rest to any command to print the REST request + response panels (method, URL, headers, body) — auth headers auto-redacted. Great for proving each command hits the public API. Also works as env: export BT_SHOW_REST=1.

1 · Create account or secret — BT-CLI

Create managed account (local, on a non-directory system)BT-CLISTATE

bt pws accounts create --system 6 --name "svc_demo01" --password 'PASSWORD' --change-frequency xdays --change-days 1 --change-time 02:00

--system takes the integer ID (6 = linhost2, Linux). Sub a real PASSWORD. Note: directory accounts (like svc_app on ad.upm.academy) require a UserPrincipalName and are onboarded via discovery, not this manual create — so the create demo uses a local system.

Create secret (Secrets Safe)BT-CLISTATE

bt pws secrets secrets create --folder bec2694b-994a-47cd-07c2-08de5e7a5e2d --title "db-admin-demo" --username admin --password 'PASSWORD'

--folder is a folder GUID (IaC-Demo). Creates a real secret in that folder.

2 · Assign policy, ownership, permissions — API

List permission flagsAPIVERIFIED

bt pws secrets safes permissions-options

Show current grants on a safeAPIVERIFIED

bt pws secrets safes permissions 9b56a95b-0a8a-4be6-de3c-08dd5118ea68

Grant permissions to a groupAPISTATE

bt pws secrets safes grant 9b56a95b-0a8a-4be6-de3c-08dd5118ea68 --group 9 --permissions "Read, Create, Edit, Delete, Share, Manage"

Flags aren't freely combinable — the server validates the whole set. Valid combos (verified live): Read · Read, Edit · Read, Create, Edit, Delete, Share · Read, Create, Edit, Delete, Share, Manage (full owner). Manage only works with the full set — Read,Edit,Manage is rejected as an "Invalid permission combination".

Revoke all permissions for a groupAPISTATE

bt pws secrets safes revoke 9b56a95b-0a8a-4be6-de3c-08dd5118ea68 --group 9

3 · Trigger verification and rotation — BT-CLI

Verify stored credential (non-destructive)BT-CLIVERIFIED

bt pws quick test -s "ad.upm.academy" -a svc_app

Ran live → Credential test PASSED for svc_app@ad.upm.academy. Quick commands accept the system name.

Rotate nowBT-CLISTATE

bt pws quick rotate -s "ad.upm.academy" -a svc_app

Fires the platform rotation/propagation. Changes the live password.

4 · Submit and approve access request — API

Submit checkout request (capture the request ID)APISTATE

bt pws credentials checkout --system "ad.upm.academy" --account "svc_app" --reason "demo" -o json

Returns a RequestID in the JSON. Requires the account to be under an access policy with a schedule your identity can use — otherwise you get "Could not find a schedule to use with this release request." If so, use quick checkout (step 5), which lists only accounts you can actually request.

List pending requestsAPIVERIFIED

bt pws credentials list --status pending

Ran live (currently "No requests found"). Also: --all, --status approved.

Approve a pending requestAPISTATE

bt pws credentials approve REQUEST_ID

REQUEST_ID is the integer from the checkout above / from credentials list.

5 · Retrieve or broker access — API

Quick checkout — the easy path (request + approve + retrieve)BT-CLISTATE

bt pws quick checkout

Run with no args to go interactive — it lists only the accounts you're actually allowed to request, you pick one, and it does request → approve → show password in one step. This sidesteps the access-policy/schedule issue above.

Quick checkout — scripted, to a variableBT-CLISTATE

PW=$(bt pws quick checkout -s "SYSTEM" -a "ACCOUNT" --raw)

Same flow, non-interactive. Fill SYSTEM/ACCOUNT with one shown in the interactive list. echo "$PW" to view.

Get a Secrets Safe secret valueAPIVERIFIED

bt pws quick get-secret "GitHub - BTSolution-Engineering/IaC-Demo/AWS" --raw

Path is Safe/Folder/SecretName. Resolved live to Secret "AWS". Drop --raw for a table view.

6 · Revoke access — API

Check in + rotate on releaseAPISTATE

bt pws credentials checkin REQUEST_ID --rotate

REQUEST_ID is an integer (from step 4/5).

List active sessions (capture the session ID)APIVERIFIED

bt pws sessions list --active

Ran live (currently "No sessions found"). The ID column is the SESSION_ID (integer) below.

Suspend session (resumable)APISTATE

bt pws sessions suspend SESSION_ID

Terminate session (permanent)APISTATE

bt pws sessions terminate SESSION_ID --force

7 · Offboard the account — BT-CLI

Offboard system (removes system + accounts + asset)BT-CLISTATE

bt pws quick offboard -s "ad.upm.academy"

Destructive: deletes ad.upm.academy (ID 19) and all its accounts incl. svc_app. Don't run unless you mean it.

8 · Export audit evidence — API

Full evidence export (JSON)APIVERIFIED

bt pws audit export --file ~/evidence.json

Defaults to BOTH requests and sessions when no flag is given. --file must be a writable path — the CLI fetches the evidence then writes the file, so a "Permission denied" here means the directory isn't writable (use ~/ or /tmp, not a read-only checkout dir).

Approved requests (CSV)APIVERIFIED

bt pws audit export --requests --status approved --file ~/svc_app-evidence.csv --format csv

Session evidence (CSV)APIVERIFIED

bt pws audit export --sessions --file ~/sessions.csv --format csv

9-10 · Integrations + API auth — out of scope

ServiceNow / SailPoint and scoped-token API auth (certs, rate limits, bulk ops) are UI/console config, not bt-cli commands — nothing to copy/paste here.