Browse documentation
Get started
Validate a request, run it from a script and read separate result and error receipts.
On this page
1. Select the existing profile
Use the installed CLI, Bash and jq. On Windows, run the shell examples in Git Bash. This walkthrough uses an authenticated research profile; set FLASHDATA_STATE_DIR to the absolute directory where that profile is stored.
Use the same OS user and state directory on every command. FLASHDATA_API_KEY overrides the saved key; leave it unset to use the profile. The CLI does not load .env files.
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata auth status --profile research --state-dir "$FLASHDATA_STATE_DIR" --jsonDefault state locations
Use your original --state-dir if you chose a custom location. auth status should report data.accessVerified: true. For an unattended deployment, import the owner key through stdin from its secret store.
| OS | Directory |
|---|---|
| Windows | %APPDATA%/FlashData |
| macOS | ~/Library/Application Support/FlashData |
| Linux | $XDG_STATE_HOME/flashdata or ~/.local/state/flashdata |
2. Validate the request and price
Save request.json, then run the free checks in the same directory. The filter prints true only when a source price is available and the balance covers one query. Stop on a nonzero exit. A price check does not reserve credits.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}set -euo pipefail
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata account balance --profile research --state-dir "$FLASHDATA_STATE_DIR" \
--json --non-interactive > balance.json
flashdata query --input request.json --dry-run --run-id cli-research-001 \
--profile research --state-dir "$FLASHDATA_STATE_DIR" \
--json --non-interactive > preflight.json
jq -e --slurpfile balance balance.json '
.ok and .data.dryRun and .data.estimateAvailable
and ($balance[0].ok == true)
and any(.data.estimate.prices[]?;
.source == "google_search" and .available == true
and (.estimatedCredits | type == "number")
and ($balance[0].data.availableCredits | type == "number")
and .estimatedCredits <= $balance[0].data.availableCredits)
' preflight.json3. Run and read the receipt
After the checks pass, save run-search.sh and run bash run-search.sh. The first successful execution submits one search. Each attempt saves its files in a new cli-run directory; the stable run ID lets the CLI reuse an earlier success for the same account, profile and state directory.
#!/usr/bin/env bash
set -euo pipefail
umask 077
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
dir=$(mktemp -d "cli-run.XXXXXX")
if ! flashdata query --input request.json --run-id cli-research-001 \
--profile research --state-dir "$FLASHDATA_STATE_DIR" \
--output "$dir/result.json" --timeout 2m --json --non-interactive \
> "$dir/receipt.json" 2> "$dir/error.json"; then
cat "$dir/error.json" >&2
printf 'Inspect saved run cli-research-001; receipts: %s\n' "$dir" >&2
exit 1
fi
jq -e '.schemaVersion == 1 and .ok == true' "$dir/receipt.json" >/dev/null
jq -e '.status == "done" and .source == "google_search"' "$dir/result.json" >/dev/null
jq -r '.results[]?.organic[]? | [.title, .link] | @tsv' "$dir/result.json"
jq '{runId, cached, usage}' "$dir/receipt.json"
printf 'Files: %s\n' "$dir"Know which file to read
The CLI envelope and the source response are different JSON documents. Without --output, the source response is in data. This example uses --output, so read source fields from the saved result.json.
| File | Read |
|---|---|
| receipt.json | ok, runId, cached, usage and the output path. A cached receipt reports the original usage, not a new charge. |
| result.json | source, status, results and usage. For Google Search, read results[].organic[]. An empty array can be a valid search result. |
| error.json | On nonzero exit, inspect error.code, error.httpStatus, error.retryAfter and any run/job IDs. |
{
"schemaVersion": 1,
"ok": true,
"runId": "cli-research-001",
"cached": false,
"data": {
"output": "cli-run.EXAMPLE/result.json"
},
"usage": {
"credits": 0.02
}
}Recover without another search
Inspect the saved run before retrying. With access to the original account, export a successful run to a filename that does not exist yet. Claiming switches from the trial account to the owner; keep previously exported trial results and use new IDs for new owner tasks. A changed request under the same run ID is rejected; use a new ID only for an intentional new task.
flashdata runs show cli-research-001 --profile research \
--state-dir "$FLASHDATA_STATE_DIR" --json
flashdata runs show cli-research-001 --result --output recovered.json \
--profile research --state-dir "$FLASHDATA_STATE_DIR" --jsonAdd scheduling when the script works
Use --recurring with installed owner access, one stable ID per scheduled occurrence and persistent state. A trial cannot run recurring work. Your host owns the schedule; the flag only checks access. Use the complete recurring-task runner for scheduled-date handling and restarts.
Optional: private download storage
For youtube download --storage-config storage.json, save only this storage object as storage.json and replace placeholders locally. The file must be private and owned by the executing user. Use the matching permission command before running a download.
{
"storage_type": "s3",
"storage_url": "YOUR_BUCKET",
"access_key": "YOUR_ACCESS_KEY",
"secret_key": "YOUR_SECRET_KEY",
"region": "us-east-1"
}chmod 600 storage.json$storagePath = (Resolve-Path -LiteralPath './storage.json').Path
$storageUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
$storageAcl = [System.Security.AccessControl.FileSecurity]::new()
$storageAcl.SetOwner($storageUser)
$storageAcl.SetAccessRuleProtection($true, $false)
$storageAcl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($storageUser, 'FullControl', 'Allow'))
Set-Acl -LiteralPath $storagePath -AclObject $storageAcl