CHANGELOG

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

<!-- released start -->

## [Unreleased]

### Fixed

- `create_maintenance_definition` with multiple host groups only including the first group in the maintenance definition for Zabbix >=6.0.
- `add_user_to_usergroup` and `remove_user_from_usergroup` using deprecated API parameters for Zabbix >=6.0.
- Commands that allow multiple names or IDs to be specified should now correctly handle searching for multiple values.

## [3.5.0](https://github.com/unioslo/zabbix-cli/releases/tag/3.5.0) - 2025-01-13

### Added

- Environment variable `ZABBIX_URL` to specify the URL for the Zabbix API.
- Session file for storing Zabbix API sessions for multiple URLs and users.
  - This allows for multiple Zabbix instances to be used without re-authenticating.
  - The session file is stored in the application's data directory by default with the name `.zabbix-cli_session.json`.
- `app.use_session_file` configuration option to enable or disable session file usage.

### Changed

- Authentication info from environment variables now take priority over the configuration file.

### Deprecated

- Auth token file. Use the new session file instead. Session files are now created by default if `app.use_auth_token_file` is set to `true` in the configuration file.
- `app.use_auth_token_file` configuration option. Use `app.use_session_file` instead.

## [3.4.2](https://github.com/unioslo/zabbix-cli/releases/tag/3.4.2) - 2024-12-16

### Changed

- `login` command re-enabled. It should now behave consistently regardless of configuration and environment.
- `login` command description updated to reflect its intended usage.
- Now uses new header-based authentication for Zabbix >=6.4 instead of passing it as a part of the request body.

### Fixed

- Authentication for Zabbix 7.2 and later. The application now correctly determines how to pass in authentication data based on the Zabbix version.

## [3.4.1](https://github.com/unioslo/zabbix-cli/releases/tag/3.4.1) - 2024-12-04

### Changed

- `create_notification_user`: Now adds users to the default user group in addition to the notification user group to match behavior in V2.
- `show_media_types`: Now shows the formatted string representation of the media type `type` field instead of an integer.
- Auth tokens and passwords from API request errors are now masked by default in output.

### Deprecated

- `login` command. It is fundamentally flawed and is slated to be removed in a future version unless a valid use case is presented.
  - Restart the application with a different configuration or launch options to change login methods instead.

### Fixed

- Ordering of User commands in the help output.
- Auth token file being written when logging in with a token.
- Custom auth token file path not being used when writing auth token file.

## [3.4.0](https://github.com/unioslo/zabbix-cli/releases/tag/3.4.0) - 2024-11-28

### Added

- New command `help` to show help for a specific command.
- New command categories:
  - `Host Group`
  - `Host Interface`
  - `Host Monitoring`
  - `Macro (Global)`
  - `Macro (User)`
  - `Media`
  - `Proxy Group`
  - `Template Group`

### Changed

- Commands are now sorted alphabetically within each category.
- Categories are now split up into more granular sections. See the `Added` section for the new categories.

### Deprecated

- `update_usergroup_permissions` command. Use `add_usergroup_permissions` instead.
  - In the future, a `remove_usergroup_permissions` command will be added to complement the `add_usergroup_permissions` command instead of complicating the `update_usergroup_permissions` command.

### Fixed

- V2-style `-C` command invocation shim. Now correctly passes arguments to the new CLI.
- Internal Typer import error after `typer==0.13.0`.

## [3.3.0](https://github.com/unioslo/zabbix-cli/releases/tag/3.3.0) - 2024-11-06

### Added

- New configuration file table `[app.output]`:
  - `format`: Default output format for commands. Defaults to `"table"`.
  - `color`: Enable or disable color output. Defaults to `true`.
  - `paging`: Enable or disable paging of output. Defaults to `false`.
  - `theme`: Color theme for output. Defaults to `"default"`.
- Application now automatically assigns deprecated config options to their new equivalents internally.
- New command `update_config` to update an outdated configuration file with new options, as well as any currently applied overrides.
- `show_config --secrets <hide|mask|plain>` option for controlling the display mode of sensitive information in the configuration file. Defaults to `mask`.
- New command `update_host` to update basic information about a host.
- New command `show_proxy_hosts` to show hosts monitored by a given proxy.

### Changed

- Custom auth (token) file paths in config now take precedence over the default path if both exist.
- Application now prompts for Zabbix API URL if missing from config.
- Default logging configuration is performed before loading the configuration file. Ensures a default logging configuration is always present.
- Authentication method + source is now logged on successful authentication.
- No longer attempts to add a user to the logging context when logging in with an auth token.
- Require at least one option to be set for `update_*` commands. Previously, these command would state that the resource was updated even if no changes were made.
- Command `add_proxy_to_group` no longer requires a local address and port argument. If not provided, the application attempts to use the proxy's `local_address` and `local_port` fields. If the proxy does not have these fields, the command fails.

### Deprecated

- Config options moved to `[app.output]` table:
  - `app.use_colors` → `app.output.color`
  - `app.use_paging` → `app.output.paging`
  - `app.output_format` → `app.output.format`

## [3.2.0](https://github.com/unioslo/zabbix-cli/releases/tag/3.2.0) - 2024-10-29

### Added

- Configurable error handling modes for bulk mode under `app.bulk_mode`:
  - `strict`: Stop on first error.
  - `continue`: Continue on command execution error, report at the end.
  - `ignore`: Ignore all errors, including command file parsing errors.
- REPL autocompletion for enums and paths.
- Auto completion for `export_configuration --directory` argument.

### Fixed

- Screen flickering on application startup when not authenticating via username and password prompt.
- `define_host_usermacro` not working as expected when using a macro name that already exists elsewhere.

## [3.1.3](https://github.com/unioslo/zabbix-cli/releases/tag/3.1.3) - 2024-10-15

### Fixed

- Empty macro names not throwing an error in macro commands.
- Pyinstaller built binary on certain Linux versions.

## [3.1.2](https://github.com/unioslo/zabbix-cli/releases/tag/3.1.2) - 2024-10-01

### Changed

- Reduced source distribution size by excluding unnecessary files.

## [3.1.1](https://github.com/unioslo/zabbix-cli/releases/tag/3.1.1) - 2024-10-01

### Added

- Publish to PyPI.

## [3.1.0](https://github.com/unioslo/zabbix-cli/releases/tag/3.1.0) - 2024-09-27

### Added

- Plugin support. See the [plugins documentation](https://unioslo.github.io/zabbix-cli/plugins/) for more information.

### Changed

- `--config` now always creates the config file at the given location if it doesn't exist.
- `show_config` now shows the absolute path to the active configuration file.

## [3.0.3](https://github.com/unioslo/zabbix-cli/releases/tag/3.0.3) - 2024-09-16

### Added

- `--limit` option for `show_*` commands to limit the number of results shown:
  - `show_usermacro_host_list`
  - `show_usermacro_template_list`
  - `show_maintenance_periods`

### Changed

- `show_host_usermacros` rendering of `automatic` field.
  - Now shows a human readable string instead of `0` or `1`.
- Example formatting.
- Hide defaults for required positional arguments.
- `show_dirs` and `init` no longer requires logging in to the Zabbix API or an existing configuration file.
- Log record format:
  - No longer includes the process ID.
  - Now includes filename, line number and function name.
- Rich markup is no longer included in log messages.
- Accessing the config when it is not loaded now uses the same sample config as `sample_config` instead of raising an exception.

### Fixed

- `show_usermacro_host_list` not showing all hosts with the given macro.
- `show_usermacro_template_list` not showing all templates with the given macro.
- Auth token file using username from config file instead of from prompt.

## [3.0.2](https://github.com/unioslo/zabbix-cli/releases/tag/3.0.2) - 2024-09-06

### Added

- `show_hosts`: `--hostgroup` option for filtering by host group names or IDs.
- `show_last_values`: ` Item ID filtering.
- `show_usergroup`: Group ID filtering.
- `show_usergroups`: Group name or ID filtering.
- `show_users`: `--sort` option for sorting results by a field.
- Status messages when fetching data from the Zabbix API in most `show_*` commands.
- `--limit` option for most `show_*` commands to limit the number of results shown.
- Environment variable `ZABBIX_API_TOKEN` for logging in with an API token.

### Fixed

- Markup errors when rendering Zabbix items with keys containing special characters.
- Environment variables not matching V2 names.
  - Before: `ZABBIX_CLI_USERNAME`, `ZABBIX_CLI_PASSWORD`
  - After: `ZABBIX_USERNAME`, `ZABBIX_PASSWORD`

## [3.0.1](https://github.com/unioslo/zabbix-cli/releases/tag/3.0.1) - 2024-09-05

### Changed

- `migrate_config` no longer requires logging in to the Zabbix API.

### Fixed

- `migrate_config` not migrating username to the new `api.username` field in the resulting TOML configuration file.
- `migrate_config` using `legacy_json_format = true` in the resulting TOML configuration file by default.
  - Can force the old JSON format with the new `--legacy-json-format` flag.

## [3.0.0](https://github.com/unioslo/zabbix-cli/releases/tag/3.0.0) - 2024-09-02

### Added

- New CLI powered by `typer` and `click-repl`
- Shell autocompletion
- TOML configuration file support
  - Old configuration format is deprecated.
- Usage examples for most commands.
- **New configuration options:**
  - `app.default_format`: Sets the default CLI output format. Defaults to `table`.
  - `app.legacy_json_format`: Enables the old JSON output format. Defaults to `false`.
- **New commands:**
  - `add_proxy_to_group`: Add a proxy to a proxy group.
  - `create_templategroup`: Create a template group.
  - `extend_hostgroup`: Add all hosts from a host group to other host group(s) without removing them from the original group.
  - `extend_templategroup`: Add all templates from a group to other group(s) without removing them from the original group.
  - `init`: Initialize the CLI configuration file.
  - `link_template_to_template`: Link template(s) to template(s).
  - `move_hosts`: Move all hosts from one host group to another.
  - `move_templates`: Move all templates from one group to another.
  - `open`: Open a CLI directory in the system's file manager.
  - `remove_hostgroup`: Delete a host group.
  - `remove_host_interface`: Delete a host interface.
  - `remove_proxy_from_group`: Remove a proxy from a proxy group.
  - `remove_templategroup`: Delete a template group.
  - `show_dirs`: Show directories used by the CLI.
  - `show_host_interfaces`: Show interfaces for a host.
  - `show_media_types`: Show media types.
  - `show_proxies`: Show proxies.
  - `show_proxy_groups`: Show proxy groups.
  - `show_proxy_group_hosts`: Show hosts in a proxy group.
  - `show_templategroup`: Show a single template group.
  - `show_templategroups`: Show all template groups.
  - `show_user`: Show details for a single user.
  - `unlink_template_from_template`: Unlink template(s) from template(s).
  - `update_host_interface`: Update a host interface.
  - `update_user`: Update a user.
  - `update_hostgroup_proxy`: Assign a proxy to all hosts in one or more host groups.
  - `update_hostgroup_proxygroup`: Assign a proxy group to all hosts in one or more host groups.
- **New command options:**
  - `add_host_to_hostgroup`:
    - `--dryrun`: Preview changes without making them.
  - `create_host`:
    - `--name`: Host name
      - Host name still defaults to host DNS name or IP address if not specified.
    - `--description`: Host description
  - `create_hostgroup`:
    - `--rw-groups`: User groups to give RW permissions to the host group.
    - `--ro-groups`: User groups to give RO permissions to the host group. Uses groups from config file if not specified.
    - `--no-usergroup-permissions`: Do not set user group permissions. Defaults to `false`.
  - `create_host_interface`:
    - `--snmp...` TODO
  - `import_configuration`:
    - `--dryrun`: Preview files to import.
    - `--delete-missing`: Delete objects not found in the import file(s).
  - `link_template_to_host`:
    - `--dryrun`: Preview changes without making them.
  - `remove_host_from_hostgroup`:
    - `--dryrun`: Preview changes without making them.
  - `show_host`:
    - `--monitored/--unmonitored`: Filter by monitored status
    - `--maintenance/--no-maintenance`: Filter by maintenance status
    - `--active [available | unavailable | unknown ]`: Filter by active interface availability
    - Old positional filter argument syntax is deprecated.
  - `show_hosts`:
    - `--limit`: Limit number of hosts to show.
    - As well as the new `show_host` options.
  - `show_hostgroup`:
    - `--hosts/--no-hosts`: Show hosts in the group
  - `show_hostgroups`:
    - `--hosts/--no-hosts`: Show hosts in the group
  - `show_trigger_events`
    - `--trigger-id`: Trigger ID(s) to get events for.
      - Corresponds to old positional argument 1.
    - `--host`: Host(s) to get events for.
    - `--hostgroup`: Host group(s) to get events for.
    - `--limit`: Limit number of events to show
      - Corresponds to old positional argument 2.
      - Defaults to 10 (was 1).
  - `show_usergroup`:
    - `--sort`: Sort results by a field.
  - `show_usergroups`:
    - `--sort`: Sort results by a field.
  - `show_usergroup_permissions`:
    - `--sort`: Sort results by a field.
  - `unlink_template_from_host`:
    - `--dryrun`: Preview changes.
  - `update_host_proxy`:
    - `--dryrun`: Preview changes.
- **New command arguments:**
  - `show_templates`:
    - `template_names`: Template name(s) to filter by. Shows all templates by default. Supports wildcards.
  - `show_hostgroup`:
    - `name`: Host group name(s) to filter by. Shows all host groups by default. Supports wildcards.

### Changed

- Commands now take named options instead of positional arguments.
  - Positional arguments are deprecated.
- JSON output is no longer always a dict with numeric string keys.
  - See V3 migration guide for more information.
  - The old format can be enabled with the new option `app.legacy_json_format` in the new TOML configuration file.
  - When loading configuration from a legacy `.conf` file, the old format is assumed.
- **TOML configuration file option names:**
  - Table [zabbix_api] → [api]
    - `zabbix_api_url` → `url`
    - `cert_verify` → `verify_ssl`
  - Table [zabbix_config] → [app]
    - `system_id` → `username`
    - `default_directory_exports` → `export_directory`
    - `default_export_format` → `export_format`
    - `include_timestamp_export_filename` → `export_timestamps`
    - `allow_insecure_authfile` → `allow_insecure_auth_file`
  - `logging.logging` → `logging.enabled`
  - The original names are deprecated and slated for removal in a future version.
- **Configuration file defaults:**
  - `app.default_admin_usergroups` defaults to `[]` (empty list)
  - `app.default_create_user_usergroups` defaults to `[]` (empty list)
  - `app.export_timestamps` defaults to `false`
    - Exports are automatically overwritten if the file already exists.
  - `app.export_format` defaults to `json` (was `xml`)
- Application now creates a config file on launch if it doesn't exist.
- **Command changes:**
  - `create_host_interface`
    - Default port number is now determined by interface type.
      - Agent: 10050
      - SNMP: 161
      - IPMI: 623
      - JMX: 12345
  - `define_host_monitoring_status`:
    - Renamed to `monitor_host`.
  - `link_template_to_hostgroup`:
    - Renamed to `add_template_to_group`.
  - `show_host_inventory`
    - Now shows shows any inventory field that is set for the host in the table output.
    - Includes _all_ inventory fields in JSON output.
  - `show_hostgroup_permissions`:
    - Shows permissions for all host groups by default.
  - `show_proxies`:
    - Now takes a `name_or_id` argument to filter by proxy name or ID. Comma-separated. Supports wildcards.
  - `show_zabbixcli_config`:
    - Renamed to `show_config`.
  - `unlink_template_from_hostgroup`:
    - Renamed to `remove_template_from_group`.
    - No longer unlinks and clears templates from each other.
      - This was a bug/misunderstanding of the Zabbix API in the old version.
      - Use `unlink_template_from_template` to unlink and clear templates from each other.
  - `update_host_proxy`
    - Now supports setting proxy for multiple hosts at once using wildcards.
    - Output format is changed.
      - Now groups hosts by proxy prior to update.

### Deprecated

- `zabbix-cli.conf` format. Prefer the new TOML configuration file format.
- Config file options:
  - `zabbix_config.system_id` → `api.username`
- **Commands:**
  - `unlink_template_from_hostgroup`:
    - Renamed to `remove_template_from_group`.
  - `define_host_monitoring_status`:
    - Renamed to `monitor_host`
  - `show_zabbixcli_config`:
    - Renamed to `show_config`
- `zabbix-cli-init` script.
  - Replaced by `zabbix-cli init` command.
- `zabbix-cli-bulk-execution` script.
  - Replaced by `zabbix-cli --file`.

### Removed

- Support for Zabbix <1.8 login using `user.authenticate`.

### Internal

- Use Hatch for building and publishing.
- Switch from setup.py to pyproject.toml.
- Add `pre-commit` hooks.
- Add `pytest` tests
- Use Ruff for linting and formatting.
- Use Pyright for static type checking.
- API code rewritten with Pydantic data models.