neewer-cli 0.1.2

Standalone Neewer BLE CLI utility

neewer-cli

Standalone Neewer BLE command-line utility focused on fast and reliable control without a GUI.

Why This Tool

• CLI-only workflow for scripting and automation.
• Reliability controls for unstable BLE environments (retries, passes, bounded parallelism).
• Fast fixed-rig operation with config-driven --skip-discovery.
• Presets, groups, and per-light command overrides keyed by MAC.

Attribution

This project is based on and derives protocol/model support from:

• NeewerLite-Python by Zach Glenwright
• https://github.com/taburineagle/NeewerLite-Python

Requirements

• Python 3.9+
• Bluetooth adapter with BLE support

The runtime BLE dependency (bleak) is installed automatically by package install commands below.

Installation

Recommended install (PyPI):

# one-time install of pipx
python -m pip install --user pipx
python -m pipx ensurepath

# install neewer-cli
pipx install neewer-cli

Alternative user install:

python -m pip install --user neewer-cli

Upgrade:

pipx upgrade neewer-cli
# or
python -m pip install --user --upgrade neewer-cli

TestPyPI install (maintainers/testers):

python -m pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  neewer-cli==X.Y.Z

After install:

neewer-cli --help
neewer-cli --version

PyPI publishing is handled by GitHub Actions using Trusted Publishing (OIDC), with no long-lived PyPI API keys stored in GitHub.

Quick Start

# 1) discover lights
neewer-cli --list

# 2) copy example config to default config path
# Windows (PowerShell/CMD)
copy neewer.example.json %USERPROFILE%\.neewer

# macOS/Linux
cp neewer.example.json ~/.neewer

# 3) run presets
neewer-cli --preset all_on
neewer-cli --preset all_off
neewer-cli --preset key_cct_5600_30

Common Commands

# turn configured lights on/off quickly
neewer-cli --preset all_on
neewer-cli --preset all_off

# send direct command to specific MACs
neewer-cli --light D2:E2:75:8B:36:45,F8:46:85:EF:47:70 --mode CCT --temp 5600 --bri 30

# fast fixed-rig mode (no scan)
neewer-cli --light group:studio --preset all_on --skip-discovery

# power on and apply CCT in one invocation / one BLE session
neewer-cli --light group:studio --mode CCT --temp 5600 --bri 30 --power-on-first --skip-discovery

# persistent low-latency mode (keep connections open)
neewer-cli --serve --light group:studio --skip-discovery --debug

Configuration

Default config path:

• ~/.neewer (Windows: %USERPROFILE%\.neewer)

Top-level config keys:

• defaults: default CLI flags
• lights: per-MAC metadata (name, cct_only, infinity_mode, hw_mac, optional feature flags)
• groups: named MAC sets
• presets: reusable command sets
• presets.<name>.per_light: per-light command overrides in one run

Preset entries can include the same option names as CLI flags. This includes:

• power_on_first: true to send a power-on before a non-power preset command
• power_on_delay_ms: 500 to tune the delay before the follow-up command

Supported shorthand aliases inside presets and command overrides:

• power_on: true or poweron: true -> power_on_first
• power_on_delay: 500 -> power_on_delay_ms

Optional per-light feature flags in lights:

• supports_status_query: override model detection for --status query commands
• supports_extended_scene: override model detection for extended scene payloads

Reference material:

• Example config: neewer.example.json
• Wiki configuration guide: https://github.com/SergeDubovsky/neewer-cli/wiki/Configuration

Reliability Tuning

For flaky BLE environments, tune:

• --scan-attempts
• --resolve-timeout (short BLE handle resolve scan for --skip-discovery)
• --connect-retries
• --write-retries
• --passes (adaptive retries for failed lights only)
• --parallel

For stable fixed setups, keep lights fully defined in config and use --skip-discovery to reduce latency.

Advanced Protocol (Experimental)

Advanced commands are opt-in behind feature flags and still gated by per-model support.

Status query (power/channel):

neewer-cli --light group:studio --status --enable-status-query --skip-discovery

Extended scene arguments (supported models only):

neewer-cli --light group:studio --mode SCENE --scene 12 --bri 40 \
  --scene-hue-min 20 --scene-hue-max 240 --scene-speed 7 \
  --enable-extended-scene

If auto-detection is wrong for a specific light, set supports_status_query or supports_extended_scene for that MAC in config.

Serve Mode

--serve keeps BLE connections open and accepts commands from stdin:

neewer-cli --serve --light group:studio --skip-discovery --debug

Interactive commands:

• on
• off
• cct <temp> <bri> [gm]
• hsi <hue> <sat> <bri>
• scene <effect> <bri>
• preset <name>
• help
• exit

Security

• Private vulnerability reporting is enabled.
• Code scanning (CodeQL) is enabled for python and actions.
• Secret scanning and push protection are enabled.

Please report security issues privately per SECURITY.md.

Releases

GitHub releases include wheel and source distribution artifacts:

• https://github.com/SergeDubovsky/neewer-cli/releases

Maintainer release flow:

1. Update version in pyproject.toml.
2. Run local checks (ruff, pytest, build, twine check).
3. Commit and push to main.
4. Tag and push (git tag vX.Y.Z && git push origin vX.Y.Z).
5. Release workflow:
   • builds + tests
   • publishes to TestPyPI (testpypi environment)
   • publishes to PyPI (pypi environment)
   • creates a GitHub Release with built artifacts
   • uses OIDC Trusted Publishing (no PyPI tokens in GitHub secrets)

Trusted Publishing setup requirement:

• In both TestPyPI and PyPI project settings, add this repository/workflow as a Trusted Publisher for:
  • owner/repo: SergeDubovsky/neewer-cli
  • workflow: .github/workflows/release.yml
  • environments: testpypi and pypi

Project Docs

• Wiki home: https://github.com/SergeDubovsky/neewer-cli/wiki
• Developer guide: https://github.com/SergeDubovsky/neewer-cli/wiki/Developer-Guide
• Contributing: CONTRIBUTING.md
• Release process: RELEASING.md
• Security policy: SECURITY.md
• Support policy: SUPPORT.md
• Code of conduct: CODE_OF_CONDUCT.md

License

MIT. See LICENSE.