sbm-cli

A generic command-line client for the SBM (Serena Business Manager) 12.0 JSON API.

Designed for day-to-day L3 support work and for use as a tool by AI assistants (Claude Code).

Install

# Recommended — isolated environment
uv tool install sbm-cli

# Also works
pip install sbm-cli

PATH issues? If python, uv, or sbm are not found after installation, see the PATH setup guide in the manual.

Quick start

sbm configure setup  # interactive setup wizard
sbm schema           # verify config and see available transitions
sbm list             # list open tickets
sbm get 02440942     # get ticket details

Configuration

Config is stored at ~/.sbm-cli/config.toml. Run sbm configure setup to create it interactively.

The password is stored in the system keyring — Windows Credential Manager, macOS Keychain, or GNOME Keyring/KWallet on Linux (never in the config file). On headless Linux without a keyring daemon, you are prompted for your password on each run. If you have an existing config with a plaintext password field, it is migrated automatically on the next run.

Use sbm configure transition <name> to add or update a named transition interactively. Manual editing is still needed for teams (transition IDs are instance-specific):

[connection]
host       = "https://sbm.example.com"
username   = "myuser"
verify_ssl = false          # set true for trusted certs

[defaults]
table_id   = 1000
report_ids = [2208, 2209]   # one or more reports; sbm list merges and de-duplicates them
list_fields = ["TITLE","STATE","FUNCTIONALITY","URGENCY"]  # optional; blank uses built-in default

[transitions.assign]
id              = 155
fields          = ["OWNER", "3RD_LEVEL_SPECIALIST"]
optional_fields = ["SOLUTION_STEPS"]   # optional comment field

[transitions.close]
id                      = 19
fields                  = ["RESOLUTION", "ROOT_CAUSE"]
optional_fields         = ["SOLUTION_STEPS"]
pre_transition_id       = 148
pre_transition_optional = true

[transitions.return-l2]
id     = 88
fields = ["RETURN_REASON", "RETURN_NOTE", "SOLUTION_STEPS"]  # SOLUTION_STEPS required here

[transitions.transfer]
id              = 140
fields          = ["L3_SPECIALIST_GROUP"]
optional_fields = ["SOLUTION_STEPS"]

[transitions.transfer.field_types]
L3_SPECIALIST_GROUP = "list"

[teams]
my-team = { id = 155, name = "L3 My Team" }

Transition IDs are instance-specific. Find them by inspecting browser developer tools while performing actions in the SBM web UI, or ask your SBM admin.

Multiple reports. defaults.report_ids is a list. sbm list (with no --report) queries every configured report, merges the results, and drops duplicate tickets (a ticket appearing in more than one report is listed once). If one report fails, the others still return and a warning is printed to stderr; sbm list only errors when every report fails. Override the config for a single run with a repeatable --report flag: sbm list --report 2208 --report 2209.

Migration: an older config with a single report_id = 2208 is still read (treated as report_ids = [2208]) and rewritten to report_ids the next time the config is saved.

Commands

Global flags

Global flags must appear before the subcommand: sbm --pretty list, not sbm list --pretty.

--version       Show installed version and exit
--pretty / -H   Human-readable output (rich tables)
--config PATH   Override config file location
--quiet         Suppress stderr status messages
--indent        Output formatted JSON with indentation

Output format

All commands output a JSON envelope:

{"ok": true, "command": "get", "data": {...}}
{"ok": false, "command": "transition", "error": {"type": "api_error", "message": "..."}}

Exit codes: 0 success · 1 API error · 2 config/auth error · 3 validation error

Development

git clone https://github.com/xdoko01/sbm-cli
cd sbm-cli
uv sync
uv run sbm configure
uv run pytest
uv run pytest -m integration  # requires live SBM connection

Changelog

0.6.0

• Headless / non-interactive support: SBM_CLI_PASSWORD is checked before the system keyring, so CI runners, containers and AI agents need no keyring daemon and no piping tricks. The password is never written to disk
• SBM_CLI_CONFIG sets the config file path without repeating --config on every call (precedence: --config > SBM_CLI_CONFIG > ~/.sbm-cli/config.toml)
• sbm configure export prints the full config as raw TOML on stdout (never includes a password); sbm configure import [PATH|-] validates and installs it, refusing to overwrite without --force and tolerating a UTF-8 BOM
• sbm auth check verifies credentials against the host and reports which source the password came from
• The interactive password prompt is now gated on stdin being a terminal — on redirected stdin it used to block forever, and now exits 2 with a message naming SBM_CLI_PASSWORD
• Fixed: sbm configure transition wrote to ~/.sbm-cli/config.toml unconditionally, ignoring --config

0.5.0

• Multi-report support: defaults.report_ids is now a list; sbm list (with no --report) queries every configured report, merges the results, and de-duplicates tickets
• --report is now repeatable (sbm list --report 2208 --report 2209) and overrides report_ids for that run
• Best-effort listing: a failing report is skipped with a stderr warning; sbm list errors only when every report fails
• sbm configure setup prompts for a comma-separated list of report IDs; sbm schema reports report_ids
• Backward compatible: a legacy singular report_id is read as [report_id] and migrated to report_ids on next save

0.4.0

• Cross-platform support: Windows, macOS, and Linux (previously Windows-only)
• Platform-aware credential storage messages (Windows Credential Manager / macOS Keychain / system keyring)
• Interactive password prompt fallback on headless Linux (no keyring daemon required)
• Safe config migration when no keyring is available — plaintext password preserved rather than silently lost
• pyproject.toml classifier updated to OS Independent

0.3.2

• sbm --pretty get now renders relational fields (OWNER, SUBMITTER, CONTACT, etc.) correctly — they were always blank due to a formatter bug

0.3.1

• sbm --version flag added
• README: version changelog, updated config example with optional_fields

0.3.0

• optional_fields per transition — SOLUTION_STEPS ("Add your comment") is now discoverable on all transitions via sbm schema
• sbm --pretty schema shows — optional: SOLUTION_STEPS for each supporting transition
• Named transition command warns on stderr when an unrecognised field is passed
• CLAUDE.md updated with AI instruction to ask users whether to add a comment before executing any transition

0.2.0

• Passwords stored in Windows Credential Manager (keyring); auto-migrated from plaintext config
• configure transition subcommand for interactive transition setup
• list_fields config key for customisable default columns in sbm list
• [users] config section — resolve login names to user IDs in transitions
• sbm fields command — list field dbnames, types, and labels from a sample ticket
• --indent global flag for pretty-printed JSON output

0.1.0

• Initial release: configure, schema, list, get, transition, field-values, teams
• Named transitions with required fields, pre-transition support, relational field type handling

License

MIT