wxflywheel 0.3.1

Python CLI for wx-ipad automation.

wxflywheel

Python CLI for wx-ipad automation.

Install

Requirement: Python 3.10+

Published package:

pip install wxflywheel

Local development:

cd cli
make install-dev

Authentication

export WXFLYWHEEL_KEY=your-api-key
export WXFLYWHEEL_HOST=http://host:8011

WXFLYWHEEL_KEY is required for API commands. Help output never requires a key.

Usage

wxflywheel --help
wxflywheel login --help
wxflywheel login status
wxflywheel related aggregate --keyword "社群运营"
wxflywheel search related --seed "社群运营"
wxflywheel wxindex related --keyword "社群运营"
python -m wxflywheel login status

Current Command Surface

Curated commands are intentionally published one by one. The current public command surface is:

• wxflywheel login status
• wxflywheel related aggregate --keyword "<关键词>"
• wxflywheel search related --seed "<种子词>"
• wxflywheel wxindex related --keyword "<关键词>"
• wxflywheel version / wxflywheel version show / wxflywheel version check
• wxflywheel self update

Output Contract

Command execution emits JSON. Help output remains plain text.

• Success: stdout, exit code 0
• Command/runtime errors: stderr, exit code 1
• Click argument errors: stderr, exit code 2

Schema:

{
  "code": 200,
  "data": {},
  "message": "",
  "meta": {
    "cli": {
      "current_version": "0.3.0",
      "latest_version": "0.3.1",
      "update_available": true,
      "update_severity": "patch",
      "update_command": "pip install --upgrade wxflywheel",
      "self_update_command": "wxflywheel self update",
      "changelog_url": "https://github.com/vinsew/weixin/releases/tag/wxflywheel-v0.3.1",
      "latest_release_date": "2026-04-10T12:00:00Z",
      "days_behind": 4,
      "cache_age_seconds": 120,
      "has_breaking": false,
      "python_version": "3.11.5"
    }
  }
}

Version Notifications for AI Agents

This CLI's primary users are AI Agents, not humans. Every successful command response carries a meta.cli field with 12 version-related signals so Agents can autonomously detect and decide on upgrades without any out-of-band monitoring.

How it works

1. Every command emits meta.cli — no special flag needed, it's always there.
2. 24-hour local cache — version info is cached at ~/.cache/wxflywheel/version_check.json to avoid hitting PyPI on every invocation.
3. Background refresh — when the cache is stale, a fire-and-forget subprocess worker refreshes it without blocking the current command. If subprocess spawning fails (sandboxed environments), falls back to an inline 500ms-timeout sync refresh.
4. Breaking-change detection — when a new version is found, the worker fetches the CHANGELOG from GitHub and marks update_severity = "breaking" if the new version's section contains ### Breaking, BREAKING CHANGE, or BREAKING: markers. Otherwise severity is SemVer-derived: patch / minor / major.
5. Stable schema — even when offline or cache-empty, the meta.cli object has the same 12 keys with null for unknown values. Agents never need key-exists branches.

Agent upgrade workflow

# Pseudo-code for an Agent using wxflywheel
response = run_cli("wxflywheel login status")
cli_meta = response["meta"]["cli"]

if cli_meta["update_available"]:
    severity = cli_meta["update_severity"]
    if severity == "breaking":
        # Agent should read changelog first before auto-upgrading
        notify_user(
            f"wxflywheel has a BREAKING update to {cli_meta['latest_version']}. "
            f"See {cli_meta['changelog_url']}"
        )
    elif severity in ("patch", "minor"):
        # Safe to auto-upgrade
        run_cli(cli_meta["self_update_command"])  # == "wxflywheel self update"
        # NOTE: the new version only takes effect on the NEXT invocation;
        # the currently running Agent Python process keeps the old code in memory

Manual version check

# Read from cache (fast, offline-OK)
wxflywheel version
wxflywheel version show

# Force refresh from PyPI (may take 1-10s)
wxflywheel version check

Self-update

wxflywheel self update

Invokes python -m pip install --upgrade wxflywheel in a subprocess of the current Python interpreter. Protected by a filesystem lock (~/.cache/wxflywheel/update.lock) to prevent concurrent upgrades. On success, returns before/after version and a reminder that the new version only activates on the next invocation.

Opting out (tests / CI)

Set WXFLYWHEEL_NO_META=1 to make meta a deterministic minimal stub ({"cli": {"current_version": "X.Y.Z"}}). Useful for deterministic test snapshots. wxflywheel's own test suite uses this via an autouse pytest fixture in conftest.py.

Cache directory override

Set WXFLYWHEEL_CACHE_DIR=/custom/path to override the default ~/.cache/wxflywheel. Useful for containerized environments where the home directory is read-only.

Adding a Command Module

Curated commands are intentionally added one by one. Do not expose a backend route directly just because it exists.

Minimum standard for a new curated command:

• One command maps to one stable user intent.
• Read-only commands are preferred by default.
• State-changing behavior must be explicit in the command name or behind an opt-in flag.
• Output must stay on the standard code/data/message schema.
• Command logic must use shared helpers from src/wxflywheel/commands/common.py.
• Every new command must ship with tests before registration.

Workflow:

1. Copy src/wxflywheel/commands/_template.py.
2. Replace module/action names and API parameters.
3. Add focused tests under tests.
4. Register the command in src/wxflywheel/cli.py.
5. Run the release checks before merging.

Release Checks

Repeatable release verification now lives in Makefile:

make release-check

This runs:

• ruff
• mypy
• pytest
• wheel/sdist build
• twine check
• editable-command help smoke
• built-wheel install smoke
• package rebuild from a clean dist/ / build/ state

The built package ships py.typed, so installed type checkers can treat wxflywheel as a typed package.

Optional live smoke against a real service:

export WXFLYWHEEL_HOST=http://host:8011
export WXFLYWHEEL_KEY=your-api-key
make smoke-live

Development

make install-dev
make release-check

Release Management

• Package changelog: CHANGELOG.md
• Release procedure: RELEASE.md
• GitHub Actions:
  • wxflywheel-ci.yml
  • wxflywheel-release.yml