Browse documentation
Get started
Try a Google search before signup, then connect an owner account to keep using the same CLI profile.
On this page
1. Check existing access
Run this free check in your agent's environment. If data.accessVerified is true and Google Search is permitted, reuse that access and skip to step 3. With no saved profile, continue to step 2. Resume pending or blocked access using the recovery section below.
flashdata auth status --json --non-interactiveKeep the same profile
Working access reports data.accessVerified: true, access: ready in data.identity.identity, and google_search in data.identity.permittedSources.
These commands use the default profile and work in Bash or PowerShell. For an existing named profile or custom state directory, append the same --profile NAME and --state-dir ABSOLUTE_PATH to every command, including those in a fresh terminal.
FLASHDATA_API_KEY overrides the saved key. Keep it unset when testing this profile's trial and handoff. Use the same OS user and preserve the private state directory; it holds credentials, the registration proof and run history.
Inspect credentialProtection in auth status. Windows uses DPAPI, macOS uses Keychain, and headless Linux may use an owner-only credential file. An available OS store can be required with --credential-store os.
Use an existing owner key instead
A person at a terminal can import a key through the hidden prompt below and skip trial registration and claiming. Agents should supply it on stdin with --api-key-stdin --non-interactive from their secret store; never put a key in arguments or chat.
If the profile already holds different access, review it before using auth login --replace. Importing another key is not the claim handoff. MCP OAuth is also a separate host connection.
flashdata auth login
flashdata auth status --json --non-interactive2. Start one eligible trial
Run discover first. Check data.onboardingAvailable and the allowance in data.onboarding.trial. If onboarding is available, run init once for Google Search. The server checks eligibility; the CLI saves the temporary key without opening signup or submitting a query.
flashdata discover --json --non-interactiveflashdata init --name "Research assistant" --scopes google_search --json --non-interactiveCheck the registration receipt
Expect ok: true, data.status: trial and google_search in data.connection.scopes. Read data.connection.trialExpiresAt and data.startingAllowanceCredits. The key is saved locally, not printed. If data.currentBalanceAvailable is false, rerun the free balance check before querying.
If setup already created access, reuse it. To label an agent's first registration, add --client codex --audience coding or --client openclaw --audience personal. Retain the exact input on a retry; labels do not grant permissions.
Trial allowance and limits
Request equivalents share the same starting credit balance; they are not remaining requests or independent quotas. Owner-only sources such as YouTube Download cannot spend trial credits.
| Limit | What to check |
|---|---|
| Credits / expiry | Current defaults: 1 credit for 72 hours. Read discovery for the grant and lifetime; the receipt gives the expiry and granted sources. |
| Registration | 3 registrations per IP per 24 hours, shared by users of that IP. The global trial cap may also pause new registrations. |
| Concurrency | Keep trial work sequential: one item per batch and one pending job. Check returned limits before submitting more. |
3. Try one search
Preview first. Require data.estimateAvailable, an available google_search price in data.estimate.prices, and availableCredits covering estimatedCredits. Stop if a check fails. The preview is free; the next command submits one search.
flashdata account balance --json --non-interactive
flashdata search "battery recycling" --num 5 --dry-run --json --non-interactiveflashdata search "battery recycling" --num 5 --run-id trial-search --json --non-interactiveCheck the result
Expect ok: true and data.status: done. Read titles, links and snippets from data.results[].organic, and the charge from data.usage.credits. Empty organic results are valid. Before claiming, repeating this exact task with trial-search returns its saved result. Keep the profile and state, and retain any trial results you need.
flashdata account balance --json --non-interactive4. Keep access with an owner account
Claim before the trial expires if you want continued or recurring use. When the owner is ready, run this in the original profile. Share only data.claimUrl and data.confirmationCode with them; data.expiresAt gives the deadline.
The link lasts 15 minutes, or until the trial expires if sooner. Creating the link does not approve access or purchase credits.
flashdata auth claim --json --non-interactiveApprove in the browser
- The owner opens the link and signs in, or creates a new account and verifies email. A new signup resumes the claim after verification.
- Check the account shown on the claim page. For a different or new owner, use a separate browser session. The signed-in account is the account that will pay for later requests.
- Enter the eight-digit code on that page, review product permissions and shared-balance access, then approve. The owner handles signup, legal acceptance, email verification and consent.
Finish in the original terminal
After approval, run finish in the original profile within 24 hours. The CLI saves the owner key, verifies it in a fresh process and acknowledges installation. No key is copied from the browser.
flashdata auth finish --wait --timeout 10m --json --non-interactiveflashdata auth status --json --non-interactive
flashdata account balance --json --non-interactiveConfirm the owner and balance
In auth status, verify the intended accountId and granted scopes, plus the fields below. Read the fresh balance separately; future requests spend the owner's shared credits. Unused temporary credits do not transfer. A new account follows normal signup eligibility; claiming adds no extra signup grant.
Claiming changes the billed account. For a new task under the owner, choose a new run ID. Reusing a trial run ID returns run_account_mismatch without submitting another query; it does not transfer that run to the owner.
{
"ok": true,
"data": {
"accessVerified": true,
"identity": {
"identity": {
"accountType": "owned",
"access": "ready",
"installed": true,
"recurringAllowed": true
}
}
}
}Choose product permissions
The HTTP permission catalog separates trialEligible from ownerAllowed. Request only the sources needed by your task before the first registration. requestedScopes is the request; scopes is the key's current access. New products require an explicit grant.
Approval uses the owner's shared balance, including purchased credits. Source restrictions do not create a per-agent spending cap. MCP OAuth is a separate connection and does not claim this CLI profile.
Only need YouTube Download?
Use an owner key with youtube_download permission, import it, then configure destination storage. Download does not use temporary trial credits.
CLI 1.2.1 still requires a trial-eligible source for init. For Download-only onboarding before signup, use the HTTP claim flow in auth.md. Do not add an unrelated trial source just to bypass that client restriction.
Resume a stopped flow
| What stopped | Next action |
|---|---|
| Register | For 429, wait for Retry-After. For a lost response, retry init with the same profile, proof and exact input. Keep existing state; do not switch IP or start a replacement trial. |
| Search | Inspect trial-search below. A timeout does not prove that no work was accepted; do not change the run ID to force a retry. |
| Claim link | If the link expired but the trial is valid, create a fresh link in the same profile when the owner is ready. Check the signed-in owner before approval. |
| Handoff | After approval, rerun auth finish in the original profile within 24 hours. Pending approval, an interrupted wait or a lost acknowledgement does not require a new registration. |
| Expired / lost state | For an expired trial or handoff, or a lost private state directory, use owner-approved reconnection or import an owner key. |
flashdata runs show trial-search --json --non-interactive