Metadata-Version: 2.4
Name: ydderd-flywheel-cli
Version: 0.2.0
Summary: Flywheel customer CLI — authenticate and bulk-upload field data to your workspace.
Project-URL: Homepage, https://withflywheel.com
Project-URL: Repository, https://github.com/ydderd/flywheel
Author: Flywheel
License: Apache-2.0
Keywords: cli,flywheel,ingest,upload
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: boto3>=1.34
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 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

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

## Usage

```bash
flywheel auth login --token <fw_cli_…>   # token minted by a workspace admin in Settings
flywheel auth whoami                      # confirm tenant
flywheel upload ./your-data --scan        # bulk upload + trigger ingest
flywheel ingest status                    # ingest ledger stats
```

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://api.withflywheel.com`).

Point the CLI at a local backend during development:

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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.

