flashdata-cli 1.1.0__py3-none-macosx_13_0_arm64.whl

flashdata_cli/share/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,18 @@
+# Third-party notices
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+License and notice texts copied from the dependencies pinned by current go.mod. FlashData source is covered by [LICENSE](LICENSE). These copies do not change upstream license terms.
+
+| Component | Version | License / notice text |
+| --- | --- | --- |
+| `github.com/ebitengine/purego` | v0.9.0 | [LICENSE](licenses/github.com_ebitengine_purego_v0.9.0_LICENSE.txt) |
+| `github.com/flashdatadev/flashdata-go` | v1.1.0 | [LICENSE](licenses/github.com_flashdatadev_flashdata-go_v1.1.0_LICENSE.txt) |
+| `github.com/godbus/dbus/v5` | v5.1.0 | [LICENSE](licenses/github.com_godbus_dbus_v5_v5.1.0_LICENSE.txt) |
+| `github.com/spf13/cobra` | v1.10.2 | [LICENSE.txt](licenses/github.com_spf13_cobra_v1.10.2_LICENSE.txt) |
+| `github.com/spf13/pflag` | v1.0.9 | [LICENSE](licenses/github.com_spf13_pflag_v1.0.9_LICENSE.txt) |
+| `golang.org/x/sys` | v0.36.0 | [LICENSE](licenses/golang.org_x_sys_v0.36.0_LICENSE.txt) |
+| `golang.org/x/term` | v0.35.0 | [LICENSE](licenses/golang.org_x_term_v0.35.0_LICENSE.txt) |
+| `github.com/inconshreveable/mousetrap` | v1.1.0 | [LICENSE](licenses/github.com_inconshreveable_mousetrap_v1.1.0_LICENSE.txt) |
+| `github.com/santhosh-tekuri/jsonschema/v5` | v5.3.1 | [LICENSE](licenses/github.com_santhosh-tekuri_jsonschema_v5_v5.3.1_LICENSE.txt) |
+| `Go standard library` | 1.27.3 | [LICENSE](licenses/Go_standard_library_1.27.3_LICENSE.txt) |

flashdata_cli/share/docs/bulk.md

@@ -0,0 +1,29 @@
+# Bulk data and media delivery
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+See the complete commands in the [English README](../README.md#complete-bulk-workflow) or [简体中文](../README.zh-CN.md). Supported sources are youtube_metadata, youtube_transcript, youtube_captions, youtube_trainability and youtube_download. Options are validated through the Go SDK before job creation.
+
+`bulk run` checks the ID file, private option/storage files, output path, scopes and recurring requirements, then commits intent. It creates one job, atomically stores the signed upload descriptor and run-to-job link in the protected vault, commits the remote ID in the journal, uploads once, starts and waits. A crash between vault and journal commits can recover the remote ID from the private link. The public receipt never includes the upload URL.
+
+A repeated existing run never uploads or creates another task. `runs recover` performs safe status/result reads only. If input/start is missing, it returns explicit instructions for `bulk upload` and `bulk start`. Upload binds to the SHA-256 of the original file; another file conflicts. Explicit same-file PUT retry is only permitted while the same draft awaits input and the original URL remains valid. A lost start response is resolved by Get; an already-started job is not started again.
+
+Bulk control commands operate on existing IDs: get/list/start/pause/resume/cancel/wait/results/update. `resume` requires a paused job and an explicit command after correcting its cause. `update --input` accepts a private JSON object containing partial options and callback_url (string or null to remove). Data result copies use options.result_storage; media download destination uses options.storage. Server-side credential merging and provider rules remain authoritative.
+
+Manual metadata inputs are provided as examples/bulk-create.json and examples/bulk-update.json. Both create and update accept --input -; pipe these non-secret examples directly on PowerShell or redirect them on Bash as described in the command reference and source inputs. Apply the metadata options example before upload/start. Once a scan is complete, the backend permits only the documented credential-only result_storage patch on a paused customer-delivery job; a generic options patch is not valid in that state. A paused coordinator may need time to release its lease before updates are allowed. Control commands refresh local stages, and signed upload capabilities are discarded after the job leaves awaiting_upload.
+
+ID files contain one 11-character video ID per line, from 1 byte through 2 GiB. Upload capability expires after 15 minutes; internal results remain for 24 hours. Customer buckets follow their own retention. SDK limits bound each compressed/decompressed part to 64 MiB and each row to 16 MiB by default. CLI result export streams across parts without assembling the whole dataset in memory.
+
+Validation streams the IDs into a private temporary snapshot. The hash, byte count and upload all use that snapshot, so editing or appending to the original file during API calls cannot change the validated upload. Temporary disk space up to the input size is required, including for a dry-run. Snapshots are removed when the command returns; a forcibly killed process may leave a private flashdata-ids-*.tmp file in the OS temporary directory. Preserve active snapshots until the owning process exits before any manual cleanup.
+
+S3, S3-compatible, OSS, GCS, Azure, COS, BOS and TOS shapes are supported. storage_url is a bucket/container name. GCS requires a service account; Azure needs account_name and a write-capable SAS; provider endpoint/region/permissions must be valid. No example invents real credentials. Media files are delivered into your cloud destination; JSONL reports outcomes, not video bytes.
+
+Check each row's status, even for a completed job. The CLI preserves invalid/failed rows and exits nonzero for item failures. A malformed/interrupted stream leaves a partial export; inspect/recover by run ID using a fresh output filename. Disk failures preserve the original intent/remote ID wherever possible, and never authorize replaying creation. An expired upload capability is not renewed by creating another job automatically.
+
+## Lost responses and partial receipts
+
+A lost start response keeps the original bulk ID and input fingerprint. `runs recover` first reads current remote state; after observing that input upload is no longer permitted it removes spent upload capabilities, then fetches results without another create, upload or start. Partial gzip/result transfers remain partial during cached exports, retain available rows and exit nonzero. Corrected safe result reads can complete the original journal.
+
+MP3 audio and MP4 video use the same lifecycle; choose the matching private options file
+shown in the README. See the [SDK and CLI comparison](sdk-parity.md) for all source
+coverage, media examples and recovery differences.

flashdata_cli/share/docs/commands.md

@@ -0,0 +1,548 @@
+# Command reference
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+Generated from `flashdata commands --json`. Every operational command supports the global profile, state directory, credential protection, timeout and output-mode flags. Keys are accepted only through hidden input/stdin or an explicitly configured environment variable.
+
+This reference describes CLI v1.1.0, including JSON, plain-text and Markdown response flags. See [response formats](response-formats.md) for examples. `discover plans` and `discover status` read public endpoints without an API key.
+
+## flashdata
+
+FlashData search, YouTube and bulk data workflows
+
+Usage: `flashdata`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--credential-store` | string | `auto` | auto, os, or file (protected persistent file) |
+| `--data-origin` | string | `` | pin the data origin for a new profile |
+| `--json` | bool | `false` | versioned machine-readable output |
+| `--management-origin` | string | `` | pin the management origin for a new profile |
+| `--non-interactive` | bool | `false` | disable prompts and browser opening |
+| `--profile` | string | `default` | isolated saved connection |
+| `--state-dir` | string | `` | private persistent state directory |
+| `--timeout` | duration | `2m0s` | overall command deadline; accepted server work continues |
+| `--version` | bool | `false` | show version offline |
+| `--web-origin` | string | `` | pin the browser origin for a new profile |
+
+## flashdata account
+
+Read shared balance, source pricing, limits and usage
+
+Usage: `account`
+
+## flashdata account balance
+
+Read account balance without submitting paid work
+
+Usage: `balance`
+
+## flashdata account limits
+
+Read account limits without submitting paid work
+
+Usage: `limits`
+
+## flashdata account pricing
+
+Read account pricing without submitting paid work
+
+Usage: `pricing`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--request-count` | int | `1` | estimate this many requests |
+| `--source` | string | `` | filter by source |
+
+## flashdata account usage
+
+Read account usage without submitting paid work
+
+Usage: `usage`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--from` | string | `` | RFC3339 start time |
+| `--source` | string | `` | filter by source |
+| `--to` | string | `` | RFC3339 end time |
+
+## flashdata auth
+
+Manage API-key profiles and browser claiming
+
+Usage: `auth`
+
+## flashdata auth claim
+
+Create the browser approval URL and separate confirmation code
+
+Usage: `claim`
+
+## flashdata auth finish
+
+Save, independently verify and acknowledge the approved owner key
+
+Usage: `finish`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--wait` | bool | `false` | wait for browser approval within --timeout |
+
+## flashdata auth login
+
+Import and verify an API key using hidden input or stdin
+
+Usage: `login`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--api-key-stdin` | bool | `false` | read exactly one API key from standard input |
+| `--replace` | bool | `false` | explicitly replace saved onboarding credentials, retaining history |
+
+## flashdata auth logout
+
+Remove local credentials and retain run history; does not revoke remote access
+
+Usage: `logout`
+
+## flashdata auth migrate
+
+Explicitly migrate the version-2 script state without resetting history
+
+Usage: `migrate`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--from` | string | `` | legacy private connection.json file |
+
+## flashdata auth status
+
+Verify access, scopes, expiry and claim status
+
+Usage: `status`
+
+## flashdata batch
+
+Background mixed-source batch submission
+
+Usage: `batch`
+
+## flashdata batch submit
+
+Validate all input and submit a batch once
+
+Usage: `submit`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--input` | string | `` | JSON file, or - for stdin |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+| `--wait` | bool | `false` | wait for all accepted batch jobs |
+
+## flashdata bulk
+
+Create, upload, control and recover durable bulk tasks
+
+Usage: `bulk`
+
+## flashdata bulk cancel
+
+cancel an existing bulk job; never creates replacement work
+
+Usage: `cancel BULK_ID`
+
+## flashdata bulk create
+
+Create a bulk draft once and privately retain its signed upload capability
+
+Usage: `create`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--input` | string | `` | private CreateBulkJobRequest JSON file, or - for stdin |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+
+## flashdata bulk get
+
+get an existing bulk job; never creates replacement work
+
+Usage: `get BULK_ID`
+
+## flashdata bulk list
+
+List existing remote bulk jobs
+
+Usage: `list`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--cursor` | string | `` | opaque page cursor |
+| `--limit` | int | `20` | page size, 1–50 |
+
+## flashdata bulk pause
+
+pause an existing bulk job; never creates replacement work
+
+Usage: `pause BULK_ID`
+
+## flashdata bulk results
+
+results an existing bulk job; never creates replacement work
+
+Usage: `results BULK_ID`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--output` | string | `` | new NDJSON receipt output file |
+| `--run-id` | string | `` | local recovery record to reuse |
+
+## flashdata bulk resume
+
+resume an existing bulk job; never creates replacement work
+
+Usage: `resume BULK_ID`
+
+## flashdata bulk run
+
+Create once, upload IDs, start, wait and save NDJSON receipts
+
+Usage: `run`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--input` | string | `` | UTF-8 video-ID file |
+| `--options` | string | `` | private shared source-options JSON file |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+| `--source` | string | `youtube_metadata` | one of five YouTube bulk sources |
+| `--storage-config` | string | `` | private customer storage JSON |
+
+## flashdata bulk start
+
+start an existing bulk job; never creates replacement work
+
+Usage: `start BULK_ID`
+
+## flashdata bulk update
+
+update an existing bulk job; never creates replacement work
+
+Usage: `update BULK_ID`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--input` | string | `` | private partial options/callback JSON file, or - for stdin |
+
+## flashdata bulk upload
+
+Explicitly upload the original ID file to a saved draft
+
+Usage: `upload BULK_ID`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--input` | string | `` | original video-ID file |
+| `--run-id` | string | `` | owning local run ID (auto-detected when unique) |
+
+## flashdata bulk wait
+
+wait an existing bulk job; never creates replacement work
+
+Usage: `wait BULK_ID`
+
+## flashdata commands
+
+Return the command tree for agent discovery
+
+Usage: `commands`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--help` | bool | `false` | help for commands |
+
+## flashdata discover
+
+Read service health, onboarding capabilities and documentation
+
+Usage: `discover`
+
+## flashdata discover plans
+
+Read the public plan catalog without an API key
+
+Usage: `plans`
+
+## flashdata discover status
+
+Read public service status without an API key
+
+Usage: `status`
+
+## flashdata doctor
+
+Diagnose storage and access without paid queries or account mutations
+
+Usage: `doctor`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--offline` | bool | `false` | inspect local storage only |
+
+## flashdata help
+
+Help about any command
+
+Usage: `help [command]`
+
+## flashdata init
+
+Reuse saved access or durably register one temporary connection
+
+Usage: `init`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--audience` | string | `coding` | coding or personal |
+| `--client` | string | `flashdata-cli` | self-reported client label |
+| `--name` | string | `` | connection name; required to start a new trial |
+| `--scopes` | string | `google_search,youtube_metadata` | comma-separated trial source names |
+
+## flashdata jobs
+
+Read, wait for and recover accepted background jobs
+
+Usage: `jobs`
+
+## flashdata jobs get
+
+get an accepted job; never submits work
+
+Usage: `get JOB_ID`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+
+## flashdata jobs result
+
+result an accepted job; never submits work
+
+Usage: `result JOB_ID`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--output` | string | `` | new result output file |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+
+## flashdata jobs wait
+
+wait an accepted job; never submits work
+
+Usage: `wait JOB_ID`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+
+## flashdata query
+
+Validate and execute a Data API JSON request
+
+Usage: `query`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--input` | string | `` | JSON file, or - for stdin |
+| `--mode` | string | `realtime` | realtime or async |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+| `--wait` | bool | `false` | wait for an accepted async job |
+
+## flashdata runs
+
+Inspect durable local history and recover known accepted work
+
+Usage: `runs`
+
+## flashdata runs list
+
+List local execution metadata without network calls
+
+Usage: `list`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--limit` | int | `100` | maximum records displayed; history is never evicted |
+
+## flashdata runs recover
+
+Read accepted remote jobs and save results; never resubmit a query or create a job
+
+Usage: `recover RUN_ID`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--output` | string | `` | new result output file |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+
+## flashdata runs show
+
+Inspect a record; --result revalidates live access before reading saved data
+
+Usage: `show RUN_ID`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--output` | string | `` | new result output file |
+| `--result` | bool | `false` | read the saved result after access verification |
+
+## flashdata search
+
+Google Search with the normal query billing and recovery path
+
+Usage: `search QUERY`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--gl` | string | `` | country code |
+| `--hl` | string | `` | interface language |
+| `--mode` | string | `realtime` | realtime or async |
+| `--num` | int64 | `0` | requested number of results |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--page` | int64 | `0` | requested page; separately billed |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+| `--wait` | bool | `false` | wait for an accepted async job |
+
+## flashdata sources
+
+Discover available, permitted and CLI-supported sources
+
+Usage: `sources`
+
+## flashdata sources list
+
+List source support and selected-key permissions
+
+Usage: `list`
+
+## flashdata sources show
+
+Show schema, defaults, modes, example and optional account pricing
+
+Usage: `show SOURCE`
+
+## flashdata youtube
+
+YouTube search, metadata, existing captions and media delivery
+
+Usage: `youtube`
+
+## flashdata youtube captions
+
+YouTube captions through the shared query workflow
+
+Usage: `captions INPUT`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--language` | string | `en` | caption language; existing tracks only |
+| `--mode` | string | `realtime` | realtime or async |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+| `--wait` | bool | `false` | wait for an accepted async job |
+
+## flashdata youtube download
+
+Deliver media to private customer storage (background only)
+
+Usage: `download VIDEO_ID`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--format` | string | `mp3` | output format |
+| `--mode` | string | `realtime` | realtime or async |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+| `--storage-config` | string | `` | private customer-storage JSON file |
+| `--wait` | bool | `false` | wait for an accepted async job |
+
+## flashdata youtube metadata
+
+YouTube metadata through the shared query workflow
+
+Usage: `metadata INPUT`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--mode` | string | `realtime` | realtime or async |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+| `--wait` | bool | `false` | wait for an accepted async job |
+
+## flashdata youtube search
+
+YouTube search through the shared query workflow
+
+Usage: `search INPUT`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--max-results` | int64 | `0` | requested number of search results |
+| `--mode` | string | `realtime` | realtime or async |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+| `--wait` | bool | `false` | wait for an accepted async job |
+
+## flashdata youtube transcript
+
+YouTube transcript through the shared query workflow
+
+Usage: `transcript INPUT`
+
+| Flag | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `--accept` | string | `application/json` | API response type: application/json or text/plain |
+| `--dry-run` | bool | `false` | validate without a paid submission |
+| `--language` | string | `en` | caption language; existing tracks only |
+| `--mode` | string | `realtime` | realtime or async |
+| `--output` | string | `` | new result or submission-receipt output file |
+| `--recurring` | bool | `false` | require verified owned/installed access |
+| `--respond-with` | string | `` | markdown for realtime or completed results; omit for original fields |
+| `--run-id` | string | `` | stable execution ID; required for recurring work |
+| `--wait` | bool | `false` | wait for an accepted async job |