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.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