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. For the Textual TUI editor, install the optional tui extra.

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

Install with TUI support:

python -m pip install --user "neewer-cli[tui]"

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
neewer-config --help
neewer-config-tui --help

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

Quick Start

# 1) open Text UI config editor (recommended onboarding)
neewer-config-tui

# 2) discover lights (optional direct scan check)
neewer-cli --list

# 3) copy example config to default config path (optional manual setup path)
# Windows (PowerShell/CMD)
copy neewer.example.json %USERPROFILE%\.neewer

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

# 4) run interactive text wizard (non-TUI fallback)
neewer-config

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

If textual is not installed, install it with:

python -m pip install "neewer-cli[tui]"
# or
python -m pip install textual

Interactive Config Editors

Two dedicated configuration tools are included:

• neewer-config: wizard-style onboarding and config editing
• neewer-config-tui: tree-based Textual TUI for live editing

neewer-config Wizard

Use this for guided onboarding or terminal-only workflows:

neewer-config

Main flows include:

• Detailed BLE scan for discoverable Neewer lights
• Create/update groups
• Configure per-light metadata (name, cct_only, infinity_mode)
• Create/maintain presets (POWER ON, POWER OFF, CCT)
• Add/remove/move lights across existing presets
• Edit per-light CCT parameters in existing presets

neewer-config-tui Tree Editor

Use this for a visual workflow:

neewer-config-tui

Layout:

• Scan findings panel at top
• Config tree on left (Presets, Groups, Lights)
• Context editor on right for preset defaults, per-light overrides, and light metadata

Presence validation:

• ✓ bright white: light confirmed in latest scan
• ? grey: configured light not seen in latest scan

Assignment workflow:

1. Scan lights.
2. Select a scanned light in the top selector.
3. Select target Group or Preset node in the tree.
4. Use Assign -> Group or Assign -> Preset.

Key bindings:

• Ctrl+F: scan
• Ctrl+S: save
• Ctrl+R: reload
• q: quit (double-press if unsaved changes)

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
• Configuration guide (repo mirror): docs/wiki/Configuration.md
• Interactive editor guide (repo mirror): docs/wiki/Interactive-Config-Editors.md
• 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.