Davide Scaini
161 lines
5.1 KiB
Markdown
161 lines
5.1 KiB
Markdown
# CLI reference
|
|
|
|
All commands are run via `uv run bincio <command>` from the project root.
|
|
|
|
---
|
|
|
|
## bincio extract
|
|
|
|
Extract GPX/FIT/TCX files into a BAS data store.
|
|
|
|
```bash
|
|
uv run bincio extract [OPTIONS]
|
|
```
|
|
|
|
| Option | Default | Description |
|
|
|---|---|---|
|
|
| `--config PATH` | `extract_config.yaml` | Path to config file |
|
|
| `--input DIR` | from config | Input directory (scanned recursively) |
|
|
| `--output DIR` | from config | Output BAS data store directory |
|
|
| `--file PATH` | — | Extract a single file, print JSON to stdout |
|
|
| `--since DATE` | — | Only process files newer than this date (YYYY-MM-DD) |
|
|
| `--dev N` | — | Dev mode: sample N files evenly, output to `/tmp/bincio_dev/` |
|
|
|
|
Extraction is incremental by default — unchanged files (same hash) are skipped. To force a full re-extract: `rm -rf <output_dir>`.
|
|
|
|
Supported formats: GPX, FIT, TCX — all with optional `.gz` compression.
|
|
|
|
---
|
|
|
|
## bincio render
|
|
|
|
Merge sidecar edits and build (or serve) the Astro site.
|
|
|
|
```bash
|
|
uv run bincio render [OPTIONS]
|
|
```
|
|
|
|
| Option | Default | Description |
|
|
|---|---|---|
|
|
| `--data-dir DIR` | auto-detected | BAS data store |
|
|
| `--site-dir DIR` | `./site` | Astro project directory |
|
|
| `--out DIR` | `site/dist` | Build output directory |
|
|
| `--serve` | false | Start dev server instead of building |
|
|
| `--deploy TARGET` | — | Deploy after build. Currently: `github` |
|
|
| `--handle HANDLE` | — | (Multi-user) Re-merge one user's shard only, then rewrite root manifest |
|
|
|
|
`bincio render` always:
|
|
1. Runs `merge_all()` — applies sidecar edits, produces `_merged/`
|
|
2. (Multi-user) Rewrites the root `index.json` shard manifest
|
|
3. Symlinks `site/public/data` → data directory
|
|
4. Runs `astro build` (or `astro dev` with `--serve`)
|
|
|
|
Data directory auto-detection order:
|
|
1. `--data-dir` flag
|
|
2. `output.dir` in `extract_config.yaml` (if found in cwd)
|
|
3. `./site/public/data` (symlink)
|
|
4. `../bincio_data`
|
|
|
|
---
|
|
|
|
## bincio edit
|
|
|
|
Start the local single-user edit server. For personal use only — no authentication.
|
|
|
|
```bash
|
|
uv sync --extra edit # install dependencies (one-time)
|
|
uv run bincio edit [OPTIONS]
|
|
```
|
|
|
|
| Option | Default | Description |
|
|
|---|---|---|
|
|
| `--data-dir DIR` | auto-detected | BAS data store |
|
|
| `--host HOST` | `127.0.0.1` | Bind address |
|
|
| `--port PORT` | `4041` | Bind port |
|
|
| `--strava-client-id ID` | from config | Strava OAuth client ID |
|
|
| `--strava-client-secret SECRET` | from config | Strava OAuth client secret |
|
|
|
|
Set `PUBLIC_EDIT_URL=http://localhost:4041` in `site/.env` to enable the Edit button and Upload ↑ button in the site.
|
|
|
|
Credentials resolution: `--strava-client-*` flags → `STRAVA_CLIENT_ID/SECRET` env vars → `import.strava.*` in `extract_config.yaml`.
|
|
|
|
---
|
|
|
|
## bincio init
|
|
|
|
Bootstrap a fresh multi-user instance. Run once per VPS.
|
|
|
|
```bash
|
|
uv sync --extra serve # install dependencies (one-time)
|
|
uv run bincio init [OPTIONS]
|
|
```
|
|
|
|
| Option | Required | Description |
|
|
|---|---|---|
|
|
| `--data-dir DIR` | yes | BAS data directory to initialise |
|
|
| `--handle HANDLE` | yes | Admin user handle (lowercase, URL-safe) |
|
|
| `--password PASSWORD` | yes | Admin password (prompted if omitted) |
|
|
| `--display-name NAME` | no | Admin display name (defaults to handle) |
|
|
| `--name NAME` | no | Instance name shown in the feed |
|
|
|
|
Creates:
|
|
- `instance.db` — SQLite database with users/sessions/invites tables
|
|
- `{handle}/` — admin user data directory and subdirectories
|
|
- `index.json` — root shard manifest with `"private": true`
|
|
- Prints a first invite code to stdout
|
|
|
|
Idempotent — safe to re-run. Skips steps already completed.
|
|
|
|
---
|
|
|
|
## bincio serve
|
|
|
|
Start the multi-user application server (VPS mode).
|
|
|
|
```bash
|
|
uv run bincio serve [OPTIONS]
|
|
```
|
|
|
|
| Option | Default | Description |
|
|
|---|---|---|
|
|
| `--data-dir DIR` | required | BAS data directory (must contain `instance.db`) |
|
|
| `--site-dir DIR` | — | Astro site dir — enables post-write incremental rebuilds |
|
|
| `--host HOST` | `127.0.0.1` | Bind address (keep on localhost; nginx proxies from outside) |
|
|
| `--port PORT` | `4041` | Bind port |
|
|
|
|
Requires `bincio init` to have been run first. Handles auth, user management, and write operations. nginx is responsible for serving static files and proxying `/api/*` to this server.
|
|
|
|
See [multi-user deployment](../deployment/multi-user.md) for nginx configuration.
|
|
|
|
---
|
|
|
|
## bincio import strava
|
|
|
|
Import activities directly from the Strava API.
|
|
|
|
```bash
|
|
uv sync --extra strava
|
|
uv run bincio import strava [OPTIONS]
|
|
```
|
|
|
|
| Option | Default | Description |
|
|
|---|---|---|
|
|
| `--output DIR` | from config | BAS data store output directory |
|
|
| `--since DATE` | last sync | Only import activities after this date |
|
|
| `--reauth` | false | Force a new OAuth flow even if a token exists |
|
|
| `--dev N` | — | Dev mode: import N most recent activities to `/tmp/bincio_dev/` |
|
|
|
|
Credentials: set `import.strava.client_id` and `import.strava.client_secret` in `extract_config.yaml`. The Authorization Callback Domain in the Strava app settings must be `localhost`.
|
|
|
|
Tokens are stored in `<data_dir>/strava_token.json` and auto-refreshed.
|
|
|
|
---
|
|
|
|
## Global flags
|
|
|
|
```bash
|
|
uv run bincio --version # print version
|
|
uv run bincio --help # list commands
|
|
uv run bincio <cmd> --help # command-specific help
|
|
```
|