# Automatize com a CLI do FlashData

Validar um pedido, executá-lo a partir de um script e ler resultados separados e recibos de erro.

Referência canônica: https://flashdata.dev/pt/docs/guides/cli-automation
2026-11-04 por FlashData

<a id="profiles"></a>

## 1. Selecione o perfil existente

Use o CLI instalado, Bash e jq. No Windows, execute os exemplos de shell no Git Bash. Essa caminhada usa um perfil de pesquisa autenticado, definir FLASHDATA_STATE_DIR para o diretório absoluto onde esse perfil é armazenado.

Use o mesmo usuário OS e diretório de estado em cada comando. FLASHDATA_API_KEY sobrepõe a chave salva, deixando-a desativada para usar o perfil. O CLI não carrega arquivos env.

### Verifique o acesso salvo

```bash
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata auth status --profile research --state-dir "$FLASHDATA_STATE_DIR" --json
```

- [Ligue o CLI primeiro](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#existing-key)

<a id="profile-paths"></a>

### Localização padrão do estado

Use o seu original --state-dir Se você escolheu um local personalizado. auth status deve informar data.accessVerified: true. Para uma implantação não assistida, importe a chave do proprietário através do stdin de sua loja secreta.

| OS | Diretório |
| --- | --- |
| Windows | %APPDATA%/FlashData |
| macOS | ~/Library/Application Support/FlashData |
| Linux | XDG_STATE_HOME/flashdata ou ~/.local/state/flashdata |

- [Credenciais do servidor de provisões](https://flashdata.dev/pt/docs/guides/production-deployment/reference.md#secrets)

<a id="check"></a>

## 2. Validar o pedido e preço

Salve o request.json, então execute as verificações gratuitas no mesmo diretório. O filtro imprime true apenas quando um preço de fonte está disponível e o saldo cobre uma consulta. Pare em uma saída não zero. Uma verificação de preço não reserva créditos.

### request.json

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
```

### Bash + jq · sem submissão paga

```bash
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.json
```


<a id="json"></a>

## 3. Execute e leia o comprovante

Depois que os verificações passarem, salve run-search.sh e execute o Bash run-search.sh. A primeira execução bem sucedida submete uma busca. Cada tentativa salva seus arquivos em um novo diretório cli-run, o ID estável permite que o CLI reutilize um sucesso anterior para a mesma conta, perfil e diretório de estado.

### run-search.sh

```bash
#!/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"
```


<a id="receipt-fields"></a>

### Saiba qual arquivo ler

O envelope CLI e a fonte de resposta são diferentes documentos JSON. Sem --output, a resposta da fonte está em dados. Este exemplo usa --output, então leia os campos de origem do result.json salvo.

| Arquivo | Leia |
| --- | --- |
| receipt.json | Ok, runId, cache, uso e o caminho de saída. Um recibo em cache relata o uso original, não uma nova carga. |
| result.json | Fonte, status, resultados e uso. Para Google Search, leia results[].organic[]. Um array vazio pode ser um resultado válido. |
| error.json | Na saída não zero, inspecione error.code, error.httpStatus, error.retryAfter e qualquer run/job IDs. |

#### receipt.json · Excerto ilustrativo

```json
{
  "schemaVersion": 1,
  "ok": true,
  "runId": "cli-research-001",
  "cached": false,
  "data": {
    "output": "cli-run.EXAMPLE/result.json"
  },
  "usage": {
    "credits": 0.02
  }
}
```


<a id="recover"></a>

## Recupere-se sem outra busca

Inspecione a corrida salva antes de tentar novamente. Com acesso à conta original, exporte uma execução bem sucedida para um nome de arquivo que ainda não existe. Reclamando mudanças da conta de teste para o proprietário, mantenha os resultados de testes exportados anteriormente e use o novo IDs para novas tarefas de proprietário. Um pedido alterado sob a mesma execução ID é rejeitado; use um novo ID apenas para uma nova tarefa intencional.

### Inspecione, então exporte um sucesso salvo

```bash
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" --json
```

- [trabalhos aceitos, erros e submissões incertas](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)

<a id="recurring"></a>

## Adicione agendamento quando o script funcionar

Use --recurring com acesso instalado, um estável ID por ocorrência programada e estado persistente. Um teste não pode executar trabalhos recorrentes. Seu anfitrião é dono da agenda, a bandeira só verifica o acesso. Use o corredor de tarefas recorrentes completo para o controle de datas programadas e reinicia.

- [Executar tarefas de agente recorrentes](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md)
- [Coloque em um servidor ou recipiente](https://flashdata.dev/pt/docs/guides/production-deployment/reference.md)

<a id="storage"></a>

## Opcional: armazenamento de download privado

Para download do Youtube --storage-config storage.json, salve apenas este objeto de armazenamento como storage.json e substitua os placeholders localmente. O arquivo deve ser privado e de propriedade do usuário executor. Use o comando de permissão correspondente antes de executar um download.

### storage.json · S3

```json
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}
```

### Linux / macOS

#### Restrinja o acesso aos arquivos

```bash
chmod 600 storage.json
```


### Windows PowerShell

#### Restrinja o acesso aos arquivos

```powershell
$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
```


- [Prestadores de armazenamento e resultados de entrega](https://flashdata.dev/pt/docs/guides/youtube-download-guide/reference.md#storage)
- [Comando de download](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#commands)

<a id="next"></a>

## Guias relacionados

- [CLI start rápido](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md)
- [Requisito histórico](https://flashdata.dev/app/jobs)
- [Armazenamento e revogação de credenciais](https://flashdata.dev/pt/docs/guides/production-deployment/reference.md#maintain)
