utem-cli

Control-plane CLI for the UTEM platform. Wiz-parity for the utem code lane (wiz iac scan / wiz docker scan analogue).

Install

From PyPI:

pip install utem

From Homebrew (tap, since the formula isn't in homebrew-core):

brew tap innavoto/utem https://github.com/Innavoto/utem-homebrew-tap
brew install innavoto/utem/utem

From source (development):

pip install -e .[dev]

Build a wheel + sdist locally:

python -m pip install build
python -m build   # -> dist/utem-<version>-py3-none-any.whl + dist/utem-<version>.tar.gz

Auth

The CLI reads three values from environment variables (or ~/.utem/config.toml):

Variable	Default	Required
UTEM_API_URL	https://utem.innavoto.com	no
UTEM_TOKEN	-	yes
UTEM_TENANT_ID	-	yes

~/.utem/config.toml example:

[utem]
api_url = "https://utem.innavoto.com"
token = "eyJhbGciOi..."
tenant_id = "00000000-0000-0000-0000-000000000000"

Examples

# 1. List repos visible to your tenant.
utem code repos --owner-type org

# 2. Trigger a scan and wait for it to finish.
utem code scan Innavoto/utem-code --wait

# 3. List the most recent critical secret findings as JSON.
utem code findings --severity critical --type secret --output json

Exit codes (scan)

Code	Meaning
0	Scan succeeded (or queued, no --wait)
1	Scan reached terminal failed state
2	--wait polling timed out
3	API or transport error

Test

pytest tests/

Release process

Releases are built and published by CI (.github/workflows/release.yml), never by hand from a laptop. The workflow is inert until a human triggers it — it never runs on a normal push/PR.

1. Bump version in pyproject.toml (and update packaging/homebrew/utem.rb's url/sha256 for the new sdist — see below).
2. Commit the bump, merge to main.
3. Tag the release commit and push the tag:

   git tag v0.2.0
   git push origin v0.2.0

   Pushing a v* tag triggers .github/workflows/release.yml, which:
   • checks out the tag, runs python -m build,
   • runs twine check dist/*,
   • publishes to PyPI via pypa/gh-action-pypi-publish using the repo secret PYPI_API_TOKEN. The same workflow also supports a manual workflow_dispatch run (from the Actions tab) for a dry run (publish=false input skips the actual twine upload/PyPI publish step so you can sanity-check the built artifacts first).
4. Homebrew tap (Innavoto/utem-homebrew-tap, Formula/utem.rb) is a separate repo and is updated manually today: after the PyPI publish succeeds, regenerate the resource stanzas with homebrew-pypi-poet against the new sdist and open a PR against the tap repo with the new url/sha256/resources. packaging/homebrew/utem.rb in this repo is the formula skeleton kept in sync with the live tap for reference/review — it is not itself installed by brew (the tap repo is).

No step in this flow runs automatically on a normal commit — publishing always requires either a pushed v* tag or an explicit manual dispatch by a human with the PYPI_API_TOKEN secret configured on the repo.