flashdata-cli 1.1.0__py3-none-macosx_13_0_arm64.whl

flashdata_cli/__init__.py

@@ -0,0 +1,32 @@
+"""Launch the bundled FlashData executable without changing CLI behavior."""
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main():
+    """Pass arguments, streams, environment and exit status to the native CLI."""
+    binary = Path(__file__).resolve().parent / "bin" / ("flashdata.exe" if os.name == "nt" else "flashdata")
+    arguments = [str(binary), *sys.argv[1:]]
+    try:
+        if os.name != "nt":
+            # Keep PID, terminal and signal handling under the native executable.
+            os.execv(str(binary), arguments)
+        # Windows has no Unix process replacement. The child shares this console
+        # and inherits stdin/stdout/stderr; Ctrl+C reaches it directly.
+        child = subprocess.Popen(arguments)
+        while True:
+            try:
+                return child.wait()
+            except KeyboardInterrupt:
+                # Let the CLI finish its own interruption/recovery handling.
+                continue
+    except OSError as error:
+        # Do not echo arguments or the environment, which can contain secrets.
+        print("Cannot start bundled FlashData executable: " + (error.strerror or "operating system error"), file=sys.stderr)
+        return 127 if isinstance(error, FileNotFoundError) else 126
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flashdata_cli/__main__.py

@@ -0,0 +1,4 @@
+"""Allow python -m flashdata_cli as well as the installed flashdata command."""
+from . import main
+
+raise SystemExit(main())

flashdata_cli/provenance.json

@@ -0,0 +1,9 @@
+{
+  "version": "1.1.0",
+  "source_commit": "604c679d60e4a0bb6e59bf9fe9006ec1c82bf787",
+  "target": "darwin/arm64",
+  "archive": "flashdata_1.1.0_darwin_arm64.tar.gz",
+  "archive_sha256": "dee0fb10a6dfdd782f310b91dd0961ca6ec09654c8bbde16a938d838435c5748",
+  "executable_sha256": "b2e7390d76c0aba756212435edd25e426f2750d323cc9722e1e02bbd7df495ee",
+  "wheel_platform": "macosx_13_0_arm64"
+}

flashdata_cli/share/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+## 1.1.0 — 2026-10-23
+
+Redact credentials escaped by the API's Markdown renderer in JSON and plain-text
+responses, including saved results and file exports. Preserve the last saved
+response when a format change cannot be committed, and retain safe recovery after
+an interruption. Cover both async and batch recovery with write-failure regressions.
+
+Add independent `--accept` and `--respond-with` flags for API responses, preserving
+JSON defaults and the CLI's `--json` envelope. Support plain-text receipts with
+durable job IDs, Markdown completed results, cached-format checks and safe
+background-result reformatting. Pin Go SDK v1.1.0, update help and
+English/Chinese documentation, and test all sources against API-generated fixtures.
+
+## 1.0.1
+
+Ship public `discover plans` and `discover status` commands in all five standalone binaries; neither needs an API key. Add English/Chinese workflow selectors, uploaded-caption and complete MP3/MP4 bulk recipes, explicit API coverage and an SDK/CLI comparison. Update release installation and upgrade instructions for Homebrew, APT and RPM. Native archive acceptance tests run the packaged binaries against mock APIs on every supported platform. The Go SDK stays pinned to v1.0.0; existing v1.0.0 release assets are unchanged.
+
+## Unreleased packaging
+
+Local `flashdata-cli` 1.0.0 PyPI wheel candidates for Linux amd64/arm64, macOS 13+ Intel/Apple Silicon and Windows amd64, with a dependency-free Python launcher, pinned executable provenance, pip/uv installation checks and English/Chinese installation/build docs. No PyPI/TestPyPI publication or change to existing release binaries/tags.
+
+## 1.0.0
+
+Standalone CLI on the Go SDK; protocol-2 onboarding and fresh-process installation; native DPAPI/Keychain/Secret Service or explicit protected files; profiles and atomic/locked state; query/search/YouTube, async/batch and complete bulk workflows; durable run recovery; account/source discovery; diagnostics; legacy migration; English/简体中文 docs; offline tests and local archives/checksums. Formal GitHub Release with five platform archives, current English/Chinese installation docs, release notes, build report and checksums; no backend deployment.
+
+Local review fixes preserve saved credentials under environment overrides and same-key imports; retain recurring policy during recovery; preserve valid public schemas; avoid per-item identity reads in batches; retain batch IDs after commit errors; protect Windows outputs from creation; enforce private credential-bearing inputs; recover large journals; refresh bulk stages and remove spent capabilities; and make migration retries safe. Added direct backend-contract checks, all-source example coverage, manual bulk JSON inputs and matching English/Chinese instructions.
+
+Final joint check: retained candidate recovery IDs across SDK/CLI wire errors; partial-export errors; lost ACK/start recovery and spent upload cleanup; generation consistency; reviewed package manifests, deterministic archives, dependency notices and reproducible package checks. Source is hosted on GitHub; no version tag, GitHub Release or backend deployment is created by the source push.
+
+The CLI pins SDK v1.0.0 and its verified checksums without a sibling replacement. Archives embed their exact source commit, include release notes and portable build reports, and ship SHA-256 checksums. CI runs native Intel macOS tests and cross-builds Apple Silicon on Go 1.25/1.27; superseded runs cancel automatically.

flashdata_cli/share/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+## Build from source
+
+With Go 1.25+ installed, clone the repository and build from its root. The Go SDK is resolved automatically from the version pinned in `go.mod`.
+
+```bash
+git clone https://github.com/flashdatadev/flashdata-cli.git
+cd flashdata-cli
+go build -trimpath -o dist/flashdata ./cmd/flashdata
+./dist/flashdata --help
+```
+
+On Windows PowerShell, after cloning and entering the directory:
+
+```powershell
+go build -trimpath -o dist/flashdata.exe ./cmd/flashdata
+.\dist\flashdata.exe --help
+```
+
+To build the published version instead of the latest source, add `--branch v1.0.0 --depth 1` to `git clone`. For normal installation, use the [installation guide](docs/installation.md).
+
+## Development checks
+
+Use Go 1.25+ and run `go mod download` to resolve the SDK revision pinned in `go.mod`; no separate SDK checkout is required. Run `go test ./...`, `go vet ./...`, `gofmt` on changed source, and race tests on a supported host. To develop both repositories together, use an explicit local `go.work` file; archive builds disable workspaces and reject SDK replacements. Do not introduce paid/live tests into the default suite. Preserve proof-before-registration, intent-before-submission, no automatic paid retries, account-bound caches, OS-lock crash safety and fresh-process verification before ACK.
+
+All HTTP/API contract logic belongs in flashdata-go. CLI compatibility normalization, secure storage, profiles, journaling, output and host scheduling boundaries belong here. Update English/Chinese docs and runnable examples together. Publication/deployment is a separate explicit request.
+
+With a local backend checkout available, optionally run `node scripts/check_backend_contracts.cjs /absolute/path/to/backend`. This reads the actual source schemas and invokes pure option/registration validators; it starts no server and makes no paid, registration, database or customer-cloud call. Node is used only for this development check, not by the executable or default Go tests.
+
+After changing commands, build the local executable and run `python scripts/generate_commands.py /absolute/path/to/flashdata` to refresh the command reference. Add `--check` to verify that it matches without writing. These are optional development tools; users run only the standalone executable.
+
+Python wheel preparation uses `packaging/pypi` and the [English packaging guide](docs/python-packaging.md) / [简体中文](docs/python-packaging.zh-CN.md). Run the packaging unit tests and native pip/uv installation checks after wrapper changes. Never introduce an installation-time binary download, shell argument forwarding or an implicit registry upload.

flashdata_cli/share/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlashData
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flashdata_cli/share/README.md

@@ -0,0 +1,251 @@
+# FlashData CLI
+
+[简体中文](README.zh-CN.md) · [FlashData](https://flashdata.dev) · [API docs](https://flashdata.dev/docs) · [Pricing](https://flashdata.dev/pricing)
+
+**Google search and YouTube data, straight from your terminal.** [FlashData](https://flashdata.dev) gives you structured search results, video metadata and existing transcripts through one API. Use `flashdata` to research a topic, feed web results to an AI assistant, build a video dataset, or deliver audio to your cloud storage.
+
+No application code is required. Commands return JSON by default, with text and Markdown options. Bulk jobs export JSONL, and saved run IDs let scripts recover accepted work after an interruption.
+
+## Choose a workflow
+
+| What you want to build | Start here |
+| --- | --- |
+| Web context and source links for an AI assistant | [Google search](#search-the-web-for-research-or-ai-context) |
+| Industry research or news monitoring | [News search](#search-the-web-for-research-or-ai-context) |
+| Video discovery for a topic or learning resource | [YouTube search](#find-youtube-videos-and-collect-their-data) |
+| Video analytics and catalog enrichment | [Video metadata](#find-youtube-videos-and-collect-their-data) |
+| Text for video summaries, search or retrieval | [Existing transcripts](#find-youtube-videos-and-collect-their-data) |
+| A dataset from a list of video IDs | [Bulk metadata export](#build-a-video-dataset-with-one-bulk-command) |
+| Audio or video files delivered to your own cloud bucket | [Bulk media download](#complete-bulk-workflow) |
+| Continue an interrupted bulk job | [Recovery](#recover-interrupted-work) |
+
+The examples collect data; your application provides summarization, indexing, scheduling
+and AI model calls.
+
+## Get started
+
+On macOS or Linux with [Homebrew](https://brew.sh):
+
+```bash
+brew install flashdatadev/tap/flashdata
+```
+
+For **Ubuntu/Debian**, **Fedora/RHEL** or **Windows**, follow the [installation guide](docs/installation.md), or download a [standalone executable](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.1.0). Native installs need no Go, Python or Node.js. Linux and macOS support Intel/AMD and ARM64; Windows supports x64.
+
+Get an API key from your [FlashData account](https://flashdata.dev). Run `auth login` and paste it at the hidden prompt, then make your first search:
+
+```bash
+flashdata auth login
+flashdata search "battery recycling startups" --num 5 --json
+```
+
+The result includes structured Google search data such as page titles, links and snippets. Your key is saved for later commands using the platform credential store where available; see [credential storage](docs/security.md). Queries and jobs use your account's credits; see [pricing](https://flashdata.dev/pricing).
+
+Looking for `pip` or `uv`? The Python installer package is **not published to PyPI yet**. Use the install methods above, or follow the [candidate-wheel guide](docs/python-packaging.md).
+
+## JSON, plain text and Markdown
+
+Version 1.1.0 includes `--accept` and `--respond-with`. Install a standalone
+release binary, or use Go 1.25+:
+
+```bash
+go install github.com/flashdatadev/flashdata-cli/cmd/flashdata@v1.1.0
+```
+
+Choose plain text or Markdown for a search:
+
+```bash
+flashdata search "vector databases" --accept text/plain
+flashdata search "vector databases" --accept text/plain --respond-with markdown
+```
+
+JSON remains the default. `--accept` also applies to async receipts, batches and
+job status. Markdown applies to realtime queries and completed results. Add
+`--json` to wrap text in the CLI envelope, or `--output FILE` to save the selected
+body. See [response formats and recovery](docs/response-formats.md).
+
+## Search the web for research or AI context
+
+Save search results to a file for your script or assistant:
+
+```bash
+flashdata search "battery recycling startups" --num 5 --output search.json
+```
+
+Use `--gl us` and `--hl en` to set the search country and interface language. For news, images, shopping, videos or places, use `query` with the matching source. For example, save this as `news-query.json`:
+
+```json
+{"source":"google_news","query":"battery recycling"}
+```
+
+Then run:
+
+```bash
+flashdata query --input news-query.json --output news.json
+```
+
+See [available sources and inputs](https://flashdata.dev/docs) or run `flashdata sources list` and `flashdata sources show google_news`.
+
+## Find YouTube videos and collect their data
+
+**Find videos about a topic:**
+
+```bash
+flashdata youtube search "Go programming tutorial" --max-results 5 --json
+```
+
+**Get a video's title, channel, duration and engagement data:**
+
+```bash
+flashdata youtube metadata dQw4w9WgXcQ --output video.json
+```
+
+**Get an existing English transcript for summarization or analysis:**
+
+```bash
+flashdata youtube transcript dQw4w9WgXcQ --language en --output transcript.json
+```
+
+Use a video ID from the search results in place of `dQw4w9WgXcQ`. Transcript availability depends on the video's existing language tracks; this does not transcribe arbitrary audio. Use `youtube captions` to request an existing manual caption track instead.
+
+**Read an existing uploaded caption track:**
+
+```bash
+flashdata youtube captions dQw4w9WgXcQ --language en --output captions.json
+```
+
+`--json` writes a machine-readable response to stdout; `--output FILE` saves the result. Choose a new output filename for each export: existing files are never overwritten.
+
+## Build a video dataset with one bulk command
+
+Create `ids.txt` with one YouTube video ID per line:
+
+```text
+dQw4w9WgXcQ
+jNQXAC9IVRw
+```
+
+Collect metadata for all IDs and export the per-video results:
+
+```bash
+flashdata bulk run --source youtube_metadata --input ids.txt --run-id video-dataset-001 --timeout 1h --output videos.jsonl
+```
+
+This command creates the job, uploads your IDs, starts processing, waits and writes `videos.jsonl`. Each line records one video's outcome and data. Change `--source` to `youtube_transcript`, `youtube_captions` or `youtube_trainability` for other bulk datasets. See the [bulk guide](docs/bulk.md) for options and item statuses.
+
+## Complete bulk workflow
+
+### Deliver audio files to your cloud bucket
+
+Use the same `ids.txt` to request MP3 audio for multiple videos. Media files are delivered **to your bucket**; the local JSONL file contains delivery receipts.
+
+**1. Configure your destination.** In a private working directory outside source control, create `storage.json` and replace every placeholder with your own S3 bucket and credentials:
+
+```json
+{
+  "storage_type": "s3",
+  "storage_url": "YOUR_BUCKET_NAME",
+  "region": "us-east-1",
+  "access_key": "YOUR_STORAGE_ACCESS_KEY",
+  "secret_key": "YOUR_STORAGE_SECRET_KEY",
+  "object_prefix": "flashdata/audio"
+}
+```
+
+Create `audio-options.json` in the same directory:
+
+```json
+{"download_type":"audio","output_format":"mp3"}
+```
+
+On Linux/macOS, make both files private before running the command:
+
+```bash
+chmod 600 storage.json audio-options.json
+```
+
+On Windows, restrict both files' ACLs to your user, SYSTEM and optionally Administrators; see [private-file requirements](docs/security.md). Other supported destinations include S3-compatible storage, OSS, GCS, Azure, COS, BOS and TOS; see [storage options](docs/bulk.md).
+
+**2. Run the complete task.** Run from the directory containing those files and `ids.txt`:
+
+```bash
+flashdata bulk run --source youtube_download --input ids.txt --storage-config storage.json --options audio-options.json --run-id audio-bulk-001 --timeout 1h --output audio-receipts.jsonl
+```
+
+The command creates, uploads, starts, waits and exports. Check `audio-receipts.jsonl` for each video's delivery status and destination. A completed job can still contain failed items; those receipts are saved and the command exits with a nonzero status.
+
+**For one video**, use the same storage configuration:
+
+```bash
+flashdata youtube download dQw4w9WgXcQ --storage-config storage.json --format mp3 --wait --timeout 30m --output audio-delivery.json
+```
+
+### Deliver MP4 video to your cloud bucket
+
+Use the same `ids.txt` and private `storage.json`, and create `video-options.json`:
+
+```json
+{"download_type":"audio_video","video_quality":"<=720","output_format":"mp4"}
+```
+
+On Linux/macOS, restrict the options file first:
+
+```bash
+chmod 600 video-options.json
+```
+
+```bash
+flashdata bulk run --source youtube_download --input ids.txt --storage-config storage.json --options video-options.json --run-id video-bulk-001 --timeout 1h --output video-receipts.jsonl
+```
+
+Video files go to the bucket; per-video delivery outcomes go to `video-receipts.jsonl`.
+On Windows, apply the same private ACL requirements as for the audio options file.
+
+### Recover interrupted work
+
+Keep the same profile and state directory. List saved runs, then recover the accepted bulk job into a fresh output file:
+
+```bash
+flashdata runs list
+flashdata runs recover audio-bulk-001 --timeout 1h --output recovered-receipts.jsonl
+```
+
+Recovery reads the existing job; it does not submit another download. For the metadata dataset above, substitute `video-dataset-001`; for MP4 delivery, use `video-bulk-001`. If an interruption occurred before upload/start, inspect the run and follow the [bulk recovery guide](docs/bulk.md). A timeout stops local waiting; accepted server work continues.
+
+Use a new run ID only when you intend to create a new task. See [run history and recovery](docs/runs.md) for scripts, uncertain submissions and partial exports.
+
+## Supported APIs
+
+| Capability | Commands |
+| --- | --- |
+| Google search, images, news, shopping, videos and places | `search`; `query --input FILE` for all six sources |
+| All nine YouTube sources | `youtube search/metadata/transcript/captions/download`; `query` for extended search, channel, suggestions, license labels and full download inputs |
+| Realtime, background and mixed batches | `query`, `query --mode async`, `batch submit` |
+| Standard jobs | `jobs get`, `jobs wait`, `jobs result` |
+| All five bulk sources and lifecycle/results | `bulk run`, manual `bulk` commands, `runs recover` |
+| Access, balance, prices, limits and usage | `auth status`, `account balance/pricing/limits/usage` |
+| Public source catalog and health | `sources list`, `discover` |
+| Public plan catalog and status | `discover plans`, `discover status` |
+
+All commands above are included in the ready-to-run **v1.1.0** release. `discover plans` and `discover status` need no API key. Upgrade an existing installation with `brew update && brew upgrade flashdatadev/tap/flashdata`, `sudo apt-get update && sudo apt-get install --only-upgrade flashdata`, or `sudo dnf --refresh upgrade flashdata`; see the [installation guide](docs/installation.md) for repository setup and Windows upgrades. Your profiles and run history are preserved.
+
+All 15 sources support background/batch execution; 14 support realtime. Downloads run in the background and require your cloud storage. Use `sources show SOURCE` for source schemas and a runnable JSON request. The single-video `youtube download` shortcut delivers audio; `query --mode async` and bulk expose the full media source options.
+
+See the [SDK and CLI comparison](docs/sdk-parity.md) and [command reference](docs/commands.md).
+
+## More workflows
+
+**Check before spending credits:** `--dry-run` validates input without submitting a paid query. Balance reads are also free.
+
+```bash
+flashdata search "battery recycling startups" --num 5 --dry-run
+flashdata account balance
+flashdata --help
+```
+
+- **Scripts and AI agents:** use `--json --non-interactive`, [profiles and credentials](docs/security.md), and [stable run IDs](docs/runs.md). Store a key through `auth login --api-key-stdin` when integrating a secret manager. An explicitly set `FLASHDATA_API_KEY` overrides the saved key for that command; `.env` files are not loaded.
+- **Background queries and mixed batches:** see the [runnable inputs](examples/README.md) and [command reference](docs/commands.md).
+- **New agent setup and browser claiming:** see [onboarding](docs/onboarding.md). This optional flow depends on server availability; existing accounts can use `auth login` directly.
+- **Use FlashData inside a Go application:** install the [Go SDK](https://github.com/flashdatadev/flashdata-go), which powers this CLI.
+
+[Installation and upgrades](docs/installation.md) · [API documentation](https://flashdata.dev/docs) · [Troubleshooting](docs/security.md) · [Contributing and source builds](CONTRIBUTING.md) · [Release notes](docs/release-notes-1.1.0.md) · [MIT license](LICENSE)

flashdata_cli/share/README.zh-CN.md

@@ -0,0 +1,250 @@
+# FlashData CLI
+
+[English](README.md) · [FlashData 官网](https://flashdata.dev) · [API 文档](https://flashdata.dev/docs) · [价格](https://flashdata.dev/pricing)
+
+**在终端直接获取 Google 搜索结果和 YouTube 数据。** [FlashData](https://flashdata.dev) 通过统一 API 提供结构化搜索结果、视频元数据和已有字幕。使用 `flashdata` 研究主题、为 AI 助手提供网页信息、构建视频数据集，或将音频交付到自己的云存储。
+
+无需编写应用代码。命令默认返回 JSON，当前源码还支持纯文本和 Markdown。批量任务导出 JSONL；保存的运行 ID 可以帮助脚本在中断后恢复已受理的任务。
+
+## 按使用场景选择工作流
+
+| 想要构建的功能 | 从这里开始 |
+| --- | --- |
+| 为 AI 助手提供网页上下文和来源链接 | [Google 搜索](#搜索网页用于研究或-ai-上下文) |
+| 行业研究或新闻监控 | [新闻搜索](#搜索网页用于研究或-ai-上下文) |
+| 按主题发现视频或学习资源 | [YouTube 搜索](#查找-youtube-视频并获取数据) |
+| 视频分析和内容目录补全 | [视频元数据](#查找-youtube-视频并获取数据) |
+| 为视频摘要、搜索或检索获取文本 | [已有字幕文本](#查找-youtube-视频并获取数据) |
+| 根据一组视频 ID 构建数据集 | [批量元数据导出](#一条批量命令构建视频数据集) |
+| 将音频或视频交付到自己的云存储桶 | [批量媒体下载](#完整批量工作流) |
+| 继续中断的批量任务 | [恢复任务](#恢复中断的任务) |
+
+以下示例负责获取数据；摘要、检索索引、调度和 AI 模型调用由应用实现。
+
+## 快速开始
+
+在已安装 [Homebrew](https://brew.sh) 的 macOS 或 Linux 上运行：
+
+```bash
+brew install flashdatadev/tap/flashdata
+```
+
+**Ubuntu/Debian**、**Fedora/RHEL** 和 **Windows** 用户请参阅[安装指南](docs/installation.zh-CN.md)，或下载[独立可执行文件](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.1.0)。原生安装无需 Go、Python 或 Node.js。Linux 和 macOS 支持 Intel/AMD 与 ARM64，Windows 支持 x64。
+
+从 [FlashData 账户](https://flashdata.dev) 获取 API 密钥。运行 `auth login`，在隐藏输入提示中粘贴密钥，然后执行第一次搜索：
+
+```bash
+flashdata auth login
+flashdata search "battery recycling startups" --num 5 --json
+```
+
+结果包含网页标题、链接和摘要等结构化 Google 搜索数据。密钥会保存供后续命令使用；平台凭据存储可用时会优先使用，详见[凭据存储](docs/security.md)。查询和任务会消耗账户额度，参见[价格](https://flashdata.dev/pricing)。
+
+想使用 `pip` 或 `uv`？Python 安装包**尚未发布到 PyPI**。请使用上述安装方式，或参阅[候选 wheel 指南](docs/python-packaging.zh-CN.md)。
+
+## JSON、纯文本和 Markdown
+
+1.1.0 正式版包含 `--accept` 和 `--respond-with`。可安装独立可执行文件，
+或使用 Go 1.25+ 安装：
+
+```bash
+go install github.com/flashdatadev/flashdata-cli/cmd/flashdata@v1.1.0
+```
+
+为搜索选择纯文本或 Markdown：
+
+```bash
+flashdata search "vector databases" --accept text/plain
+flashdata search "vector databases" --accept text/plain --respond-with markdown
+```
+
+JSON 仍是默认格式。`--accept` 也适用于后台回执、批量提交和任务状态。Markdown
+适用于实时查询和已完成结果。增加 `--json` 可将文本放入 CLI 的 JSON 输出外层，
+使用 `--output FILE` 可保存所选格式的正文。参见[响应格式与恢复](docs/response-formats.md)。
+
+## 搜索网页，用于研究或 AI 上下文
+
+将搜索结果保存为文件，供脚本或助手读取：
+
+```bash
+flashdata search "battery recycling startups" --num 5 --output search.json
+```
+
+通过 `--gl us` 和 `--hl en` 设置搜索国家及界面语言。新闻、图片、购物、视频或地点搜索可通过 `query` 指定对应来源。例如，将以下内容保存为 `news-query.json`：
+
+```json
+{"source":"google_news","query":"battery recycling"}
+```
+
+然后运行：
+
+```bash
+flashdata query --input news-query.json --output news.json
+```
+
+参阅[可用来源和输入参数](https://flashdata.dev/docs)，或运行 `flashdata sources list` 和 `flashdata sources show google_news`。
+
+## 查找 YouTube 视频并获取数据
+
+**按主题查找视频：**
+
+```bash
+flashdata youtube search "Go programming tutorial" --max-results 5 --json
+```
+
+**获取视频标题、频道、时长和互动数据：**
+
+```bash
+flashdata youtube metadata dQw4w9WgXcQ --output video.json
+```
+
+**获取已有的英文字幕，用于摘要或分析：**
+
+```bash
+flashdata youtube transcript dQw4w9WgXcQ --language en --output transcript.json
+```
+
+将 `dQw4w9WgXcQ` 替换为搜索结果中的视频 ID。字幕能否获取取决于该视频已有的语言轨道；此功能不会将任意音频转写为文字。如需已有的人工字幕轨道，使用 `youtube captions`。
+
+**读取已有的人工字幕轨道：**
+
+```bash
+flashdata youtube captions dQw4w9WgXcQ --language en --output captions.json
+```
+
+`--json` 将机器可读响应写到标准输出；`--output FILE` 将结果保存为文件。每次导出请使用新的文件名：已有文件不会被覆盖。
+
+## 一条批量命令构建视频数据集
+
+创建 `ids.txt`，每行填写一个 YouTube 视频 ID：
+
+```text
+dQw4w9WgXcQ
+jNQXAC9IVRw
+```
+
+获取所有 ID 的元数据并导出逐视频结果：
+
+```bash
+flashdata bulk run --source youtube_metadata --input ids.txt --run-id video-dataset-001 --timeout 1h --output videos.jsonl
+```
+
+此命令会创建任务、上传 ID、启动处理、等待完成，并写入 `videos.jsonl`。每行记录一个视频的处理状态和数据。将 `--source` 改为 `youtube_transcript`、`youtube_captions` 或 `youtube_trainability`，即可构建其他类型的批量数据集。选项和逐项状态说明见[批量处理指南](docs/bulk.md)。
+
+## 完整批量工作流
+
+### 将音频文件交付到云存储桶
+
+使用相同的 `ids.txt` 为多个视频请求 MP3 音频。媒体文件会交付**到你的存储桶**；本地 JSONL 文件保存交付回执。
+
+**1. 配置目标存储。** 在源码管理之外的私有工作目录中创建 `storage.json`，将所有占位符替换为自己的 S3 存储桶和凭据：
+
+```json
+{
+  "storage_type": "s3",
+  "storage_url": "YOUR_BUCKET_NAME",
+  "region": "us-east-1",
+  "access_key": "YOUR_STORAGE_ACCESS_KEY",
+  "secret_key": "YOUR_STORAGE_SECRET_KEY",
+  "object_prefix": "flashdata/audio"
+}
+```
+
+在同一目录中创建 `audio-options.json`：
+
+```json
+{"download_type":"audio","output_format":"mp3"}
+```
+
+Linux/macOS 上，在运行命令前将两个文件设为私有：
+
+```bash
+chmod 600 storage.json audio-options.json
+```
+
+Windows 上，将两个文件的 ACL 限制为当前用户、SYSTEM 以及可选的 Administrators，详见[私有文件要求](docs/security.md)。还支持 S3 兼容存储、OSS、GCS、Azure、COS、BOS 和 TOS，参见[存储选项](docs/bulk.md)。
+
+**2. 执行完整任务。** 在包含上述文件及 `ids.txt` 的目录中运行：
+
+```bash
+flashdata bulk run --source youtube_download --input ids.txt --storage-config storage.json --options audio-options.json --run-id audio-bulk-001 --timeout 1h --output audio-receipts.jsonl
+```
+
+命令会完成创建、上传、启动、等待和导出。查看 `audio-receipts.jsonl`，检查每个视频的交付状态和目标位置。即使任务已完成，也可能存在失败条目；回执会保留，命令会以非零状态退出。
+
+**只处理一个视频**时，使用相同的存储配置：
+
+```bash
+flashdata youtube download dQw4w9WgXcQ --storage-config storage.json --format mp3 --wait --timeout 30m --output audio-delivery.json
+```
+
+### 将 MP4 视频交付到云存储桶
+
+使用相同的 `ids.txt` 和私有 `storage.json`，创建 `video-options.json`：
+
+```json
+{"download_type":"audio_video","video_quality":"<=720","output_format":"mp4"}
+```
+
+Linux/macOS 上先限制文件权限：
+
+```bash
+chmod 600 video-options.json
+```
+
+```bash
+flashdata bulk run --source youtube_download --input ids.txt --storage-config storage.json --options video-options.json --run-id video-bulk-001 --timeout 1h --output video-receipts.jsonl
+```
+
+视频文件写入存储桶，逐视频交付状态写入 `video-receipts.jsonl`。
+Windows 上应使用与音频选项文件相同的私有 ACL。
+
+### 恢复中断的任务
+
+保持相同的配置和状态目录。列出保存的运行记录，然后将已受理的批量任务恢复到一个新的输出文件：
+
+```bash
+flashdata runs list
+flashdata runs recover audio-bulk-001 --timeout 1h --output recovered-receipts.jsonl
+```
+
+恢复操作读取原有任务，不会提交另一次下载。恢复上面的元数据任务时，将运行 ID 换为 `video-dataset-001`；恢复 MP4 交付时使用 `video-bulk-001`。如果在上传或启动之前中断，请检查运行记录并遵循[批量恢复指南](docs/bulk.md)。超时只会停止本地等待，已受理的服务端任务仍会继续。
+
+只有打算创建新任务时才使用新的运行 ID。脚本、结果不确定的提交和部分导出的说明见[运行历史与恢复](docs/runs.md)。
+
+## 支持的 API
+
+| 能力 | 命令 |
+| --- | --- |
+| Google 搜索、图片、新闻、购物、视频和地点 | `search`；全部六个来源均可使用 `query --input FILE` |
+| 全部九个 YouTube 来源 | `youtube search/metadata/transcript/captions/download`；扩展搜索、频道、建议、许可标签和完整下载输入使用 `query` |
+| 实时、后台和混合批次 | `query`、`query --mode async`、`batch submit` |
+| 普通后台任务 | `jobs get`、`jobs wait`、`jobs result` |
+| 全部五个批量来源、任务控制和结果 | `bulk run`、手动 `bulk` 命令、`runs recover` |
+| 访问权限、余额、定价、限制和用量 | `auth status`、`account balance/pricing/limits/usage` |
+| 公共来源目录和健康状态 | `sources list`、`discover` |
+| 公共套餐目录和服务状态 | `discover plans`、`discover status` |
+
+上述所有命令均包含在开箱即用的 **v1.1.0** 正式版中。`discover plans` 和 `discover status` 无需 API 密钥。已有安装可执行 `brew update && brew upgrade flashdatadev/tap/flashdata`、`sudo apt-get update && sudo apt-get install --only-upgrade flashdata` 或 `sudo dnf --refresh upgrade flashdata` 升级；软件源配置及 Windows 升级见[安装指南](docs/installation.zh-CN.md)。升级保留用户配置和执行历史。
+
+全部 15 个来源支持后台/批次执行，其中 14 个支持实时请求。下载在后台运行，需要自己的云存储。
+通过 `sources show SOURCE` 查看来源模式和可运行 JSON 请求。单视频 `youtube download` 快捷命令面向音频；`query --mode async` 和批量任务支持完整的媒体来源选项。
+
+参阅[各 SDK 与 CLI 对比（英文）](docs/sdk-parity.md)和[命令参考](docs/commands.md)。
+
+## 更多工作流
+
+**消耗额度前先检查：** `--dry-run` 验证输入，不提交付费查询。余额查询同样免费。
+
+```bash
+flashdata search "battery recycling startups" --num 5 --dry-run
+flashdata account balance
+flashdata --help
+```
+
+- **脚本与 AI 代理：** 使用 `--json --non-interactive`、[配置和凭据管理](docs/security.md)，以及[稳定的运行 ID](docs/runs.md)。集成密钥管理器时可通过 `auth login --api-key-stdin` 保存密钥。显式设置的 `FLASHDATA_API_KEY` 会在当前命令中覆盖已保存密钥；不会自动加载 `.env` 文件。
+- **后台查询与混合批次：** 参阅[可运行输入示例](examples/README.md)及[命令参考](docs/commands.md)。
+- **新代理接入与浏览器认领：** 参阅[接入指南](docs/onboarding.md)。此可选流程取决于服务端是否启用；已有账户可直接使用 `auth login`。
+- **在 Go 应用中使用 FlashData：** 安装本 CLI 所使用的 [Go SDK](https://github.com/flashdatadev/flashdata-go)。
+
+[安装与升级](docs/installation.zh-CN.md) · [API 文档](https://flashdata.dev/docs) · [故障排查](docs/security.md) · [参与贡献与源码构建](CONTRIBUTING.md) · [版本说明](docs/release-notes-1.1.0.md) · [MIT 许可](LICENSE)

flashdata_cli/share/SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+[FlashData](https://flashdata.dev) · [API documentation](https://flashdata.dev/docs)
+
+Read the [storage and threat model](docs/security.md). Never put API keys, proofs, signed URLs or customer-storage secrets into issue reports. Use the private support channel available from your FlashData account. No security-report email address is invented here.
+
+Default tests use dummy keys and local mock servers. Do not run undocumented live onboarding or paid calls while debugging. Preserve uncertain run records and original credential stores; deleting them is not a safe authentication repair.