ydderd-flywheel-cli 0.2.3

Flywheel customer CLI — authenticate and bulk-upload field data to your workspace.

flywheel-cli

The Flywheel customer CLI: authenticate and bulk-upload field data straight to your workspace's storage bucket, then let the platform ingest poller pull frames into your corpus.

PyPI distribution: ydderd-flywheel-cli · Homebrew formula: flywheel-cli · command: flywheel. (The clean flywheel-cli PyPI name was taken, so the distribution carries the ydderd- prefix; the import package flywheel_cli, the flywheel command, and the brew name are unaffected.)

Why this is a separate package

The CLI talks to the Flywheel API purely over HTTP (and to R2 over S3). It shares no Python code with the backend, so it ships with a tiny dependency set — httpx + boto3 — instead of the full server stack (torch, opencv, fastapi, …). That keeps the install small and avoids shipping the backend's AGPL detector to customers.

Install

brew install ydderd/flywheel/flywheel-cli
# or:
pipx install ydderd-flywheel-cli
flywheel --help

Usage

flywheel auth login                       # opens a browser; a workspace admin approves
flywheel auth whoami                      # confirm tenant
flywheel upload ./your-data --scan        # bulk upload + trigger ingest
flywheel ingest status                    # ingest ledger stats

upload auto-detects whether ./your-data is raw drone video (needs extraction) or already-extracted frames (ready to ingest directly) from file extensions — no --target needed in the common case. Pass --target ingest|raw-video explicitly to override the detection.

For headless/CI use, skip the browser with a token minted by a workspace admin: flywheel auth login --token <fw_cli_…>.

Config is stored at ~/.flywheel/config.json. Auth precedence: FLYWHEEL_CLI_TOKEN env > config file.

Developer notes

These knobs exist for Flywheel developers and are intentionally hidden from customer-facing help and docs:

• --api-url <url> on flywheel auth login — persist a non-production API base URL to the config (e.g. a local API). Hidden via argparse.SUPPRESS.
• FLYWHEEL_API_URL env — override the API base per-invocation. Takes precedence over the config file.

Precedence for the API base URL: FLYWHEEL_API_URL env > api_url in config > default (https://flywheeling.fly.dev/api — swap to a custom domain once one is live).

Point the CLI at a local backend during development:

FLYWHEEL_API_URL=http://localhost:8000 flywheel auth whoami
# or persist it:
flywheel auth login --token <fw_cli_…> --api-url http://localhost:8000

Local development

cd cli
uv sync
uv run flywheel --help
uv run pytest

Releasing (PyPI + Homebrew)

PyPI is the source of truth; the Homebrew formula wraps the published PyPI sdist.

1. Publish to PyPI — via GitHub Actions (Trusted Publishing, no token)

The .github/workflows/publish-cli.yml workflow builds and publishes over OIDC. Cut a release by pushing a namespaced tag from the monorepo default branch:

git tag cli-v0.1.0 && git push origin cli-v0.1.0

The PyPI project is ydderd-flywheel-cli, published from ydderd/flywheel via the pypi environment. (First publish activates the "pending" Trusted Publisher and creates the project.)

2. Update the Homebrew tap formula

After the PyPI release exists, point release.sh at your tap checkout — with SKIP_PUBLISH=1 it skips the upload and only fetches the published sdist's url/sha256, rewrites the formula, and regenerates its Python resource blocks:

SKIP_PUBLISH=1 \
FORMULA_PATH=/path/to/homebrew-flywheel/Formula/flywheel-cli.rb \
  cli/scripts/release.sh

Then commit + push the tap. Customers install with:

brew install ydderd/flywheel/flywheel-cli

release.sh can also publish to PyPI itself (UV_PUBLISH_TOKEN=pypi-… cli/scripts/release.sh) if you prefer a token-based local release over the GitHub Action.

Bumping a release: change version in pyproject.toml, push a new cli-v* tag, then re-run step 2.