Unofficial CLI for Yandex Monium

monium is a small, credential-free Python toolkit for building typed Logs and Traces selectors and parsing common telemetry exports locally. Version 0.2.0rc1 is explicitly offline: core commands perform no API calls, uploads, metrics, background telemetry, authentication, or network access. The opt-in logs url --open flag launches the system browser; any navigation/network activity after that is controlled by the browser, not by the CLI.

Capability matrix

Area	Supported	Boundary
Offline builders	Logs query/URL and Traces query selectors, typed operators, critical-path flag	Does not verify that a project or field exists
Offline parsers	Generic NDJSON, JSON, CSV, text adapters; neutral rows and documented OTLP JSON envelopes	JSON is materialized with a bounded input size; formats are not a claim of exact Monium export-schema compatibility
UI adapter	logs url emits a validated HTTPS-origin route	UI route is volatile and may change; --open is opt-in
Live/authenticated operations	Not registered	Current Yandex documentation does not publish a supported native Alerts/Logs read transport with enforceable project/cluster/service scope

monium capabilities reports this matrix as bounded JSON without reading credentials, probing the network, or attempting a browser fallback. In particular, it reports alerts.list, alerts.read, and logs.query.live as unavailable with reason_code: no_supported_provider; the CLI does not advertise placeholder commands that cannot complete safely.

Live-read release gate

The unavailable entries are deliberate. As of 2026-08-11, the official Monium API catalog publishes no native Alerts list/read or Monium Logs read/query endpoint with a request schema, response schema, pagination, and authentication contract. Roles and query-language documentation do not fill that gap, and the documented legacy Cloud Logging reader does not implement native Monium project/cluster/service semantics.

The three live capabilities remain unavailable until one supported provider and official contract fixtures exist. The first implementation must satisfy all of these conditions together:

• model alert ownership as AlertScope(project) and telemetry reads as TelemetryScope(project, cluster, service); a response echo is correlation data, never proof of server-side authorization or scope enforcement;
• decode the official alert definition as a closed discriminated union of threshold, expression, and multialert, preserving multiple queries, no-data variants, notifications, labels, and annotations; unknown semantics fail closed instead of being guessed or silently dropped;
• report any output transformation with explicit redacted_fields and definition_complete; heuristic redaction cannot claim a complete definition;
• enforce total request byte and node limits before authentication or provider invocation, then stream responses under hard byte caps, connect/read/total deadlines, and cancellation;
• prove list-to-read alert ID round trips, cross-scope and reserved-filter rejection, bounded pagination, oversized-response handling, and credential non-disclosure in arguments, output, and errors;
• use only a fixed, documented official endpoint and auth contract. No private console gateway, browser/session fallback, redirect-derived endpoint, or custom live endpoint is permitted.

Until those gates are evidenced, rollback and normal behavior are identical: no live command is registered and the capability reason remains no_supported_provider.

The parser preserves unknown record fields under fields up to the documented MAX_FIELDS cap (2,000 per record), normalized resource metadata under attributes, and source line/byte provenance. Records that exceed the field cap fail closed instead of silently dropping data. Successful parser payloads are additionally bounded to 8 MiB and 1,000,000 JSON nodes; rows that do not fit are omitted with an explicit warning and rows_omitted: true. It does not claim exact compatibility with any private or UI export format beyond the generic formats listed above.

Install

Python 3.11–3.14 is supported. Install a release from GitHub or use pipx:

pipx install https://github.com/kizz-tech/monium/releases/download/v0.2.0rc1/monium_cli-0.2.0rc1-py3-none-any.whl

From a checkout:

python -m pip install .
monium --version

No runtime dependency outside Python's standard library is required.

Build selectors

Logs query requires --project plus --service, or accepts --log-group-id alone or --trace-id alone. Repeated typed filters are available as --field KEY=VALUE, --glob-field KEY=PATTERN, --regex-field KEY=PATTERN, --contains-field KEY=TEXT (only message or meta.*), --number-field KEY=NUMBER for numeric equality, and --number FIELD OP VALUE (=, !=, >, >=, <, <=). There are no domain-specific request-path or status-code shortcuts.

monium logs query --project demo --service api \
  --contains "timeout" --field region=eu --number latency_ms ">=" 500

monium logs url --project demo --service api --from now-2h --to now

monium traces query --project demo --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 \
  --span-id 123 --span-status ERROR --min-duration 1s --critical-path

Trace IDs, span IDs, statuses, names, and other strings remain quoted even if they look like 123, true, or 1s; only explicitly typed durations and numbers are unquoted. Supported duration units are us, ms, s, m, and h.

logs url validates an HTTPS origin and never opens a browser unless --open is present. The URL route is a volatile UI adapter, not a live API contract.

Parse exports

Use an explicit format for stdin; auto uses safe file extensions/content recognition and rejects ambiguous stdin:

monium logs parse export.ndjson --input-format ndjson --limit 50
cat export.csv | monium logs parse - --input-format csv --summary-only
monium logs parse export.json --input-format json --include-attributes

Supported formats stream line-by-line where practical. JSON input is materialized and capped; line, total-input, nesting, integer, and summary cardinality bounds produce structured JSON errors. Output has independent hard byte and node budgets; budgeted row omission is always reported rather than silently truncating fields. The CLI remeasures the complete formatted envelope, including its final newline, and fails closed with a small non-zero JSON error if envelope formatting itself would exceed either cap. --summary-only sets rows_omitted: true; truncated still reports whether the row limit would have omitted matching rows.

The CLI is single-threaded. Python's CSV field-size setting is process-global, so parse_export(..., input_format="csv") serializes its own CSV calls; code that changes csv.field_size_limit() concurrently from outside this package is not a supported library usage.

0.2 migration note

The 0.2 selector API intentionally removes the legacy path/status shortcuts and their corresponding Python keyword arguments. The old path shortcut was a contains operation on a schema-specific metadata field; the old status shortcut was numeric exact equality on another schema-specific field. Choose your own exported schema keys with generic typed replacements, for example --contains-field meta.route=/ready and --number-field telemetry.status=503. OpenTelemetry names such as http.route/http.status_code are schema- dependent alternatives, not guaranteed equivalents. This is an explicit breaking change within the pre-1.0 API.

Configuration

Configuration is optional and non-secret. A TOML file is read only when named with --config; environment values then override it, and explicit CLI values override environment values. Only the allowlisted MONIUM_* names matching these keys are read; other environment variables are ignored. Allowed keys are project, service, cluster, ui_base_url, from_time, to_time, columns, and input_format.

project = "demo"
service = "api"
cluster = "production"
ui_base_url = "https://monium.yandex.cloud"
columns = ["level", "time", "message"]

MONIUM_SERVICE=worker monium --config monium.toml logs query
monium --no-config logs query --project demo --service api

Unknown TOML keys—including credential-like key names—are rejected. Values are not secret-scanned, so do not place secrets in configuration. No token, cookie, or credential environment variable is handled; only the allowlisted names above are read. Successful responses echo the effective configured values in a config object.

Security and privacy

The CLI is offline and credential-free. It does not read tokens/cookies or send files anywhere. Avoid placing secrets in command arguments, shell history, exports, config files, or bug reports. Malformed input is reported as bounded JSON errors without tracebacks. See SECURITY.md for reporting guidance.

The package contains no adapter for the Monium web console's private gateway. It never imports a browser session, cookies, CSRF state, or private console routes. A future live provider must use a supported upstream contract and must prove its server-side scope semantics before its commands can become available. Client-side response echoes or filtering do not constitute that proof.

For service documentation, consult the official Monium documentation.

This project is not affiliated with, sponsored by, or endorsed by Yandex Cloud. “Monium” and “Yandex Cloud” are used only to identify the service with which this unofficial tool interoperates.

Development

make test
make check
make build

Tests use only the standard library and never require network access or credentials. See CONTRIBUTING.md and CHANGELOG.md for project workflow and release notes.