sbm-cli 0.3.1

CLI client for SBM 12.0 JSON API

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

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 Windows Credential Manager (never in the config file). 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_id = 2208
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.

Commands

Command	Description
sbm configure setup	Interactive setup wizard
sbm configure transition <name>	Add/update a named transition interactively
sbm schema	Machine-readable capabilities JSON
sbm list [--report N] [--filter N]	List tickets
sbm get <ticket-id>	Get ticket by display ID
sbm fields <ticket-id> [--fields F1,F2]	List field definitions (dbnames, types, labels)
sbm transition <name> <ticket-id> --field K=V	Run named transition
sbm transition run <ticket-id> --id N --field K=V	Run raw transition by ID
sbm field-values <field> --table <table-id>	Discover valid relational field values
sbm teams	List configured teams

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