CLI automation

Use --format json for one final structured result or --format ndjson for streamed events. Progress is written to stderr, so stdout can be redirected safely. Add --quiet when a scheduler should suppress human progress lines.

POSIX shell example

Inject the API key through your CI or secret manager rather than storing it in the script:

#!/usr/bin/env bash
set -euo pipefail

: "${PACKETSAFARI_BASE_URL:?Set PACKETSAFARI_BASE_URL}"
: "${PACKETSAFARI_API_KEY:?Set PACKETSAFARI_API_KEY}"

PCAP="${1:?Usage: verify-capture CAPTURE.pcap}"
OUTPUT="${2:-packetsafari-result.json}"
test -f "$PCAP"

packetsafari investigate "$PCAP" \
  --goal security \
  --workflow fast \
  --format json \
  --quiet >"$OUTPUT"

python3 -m json.tool "$OUTPUT" >/dev/null
printf 'Saved %s\n' "$OUTPUT"

Retain the job ID printed in verbose output or returned in JSON. If the observer disconnects after submission, resume that same job instead of creating another:

packetsafari investigate --job-id JOB_ID --format json --quiet >result.json

Use an explicit --idempotency-key when your scheduler may retry submission. Reuse that key only for the same capture and effective settings.

PowerShell example

param(
  [Parameter(Mandatory = $true)][string]$Pcap,
  [string]$Output = 'packetsafari-result.json'
)

if (-not $env:PACKETSAFARI_BASE_URL) { throw 'Set PACKETSAFARI_BASE_URL' }
if (-not $env:PACKETSAFARI_API_KEY) { throw 'Set PACKETSAFARI_API_KEY' }
if (-not (Test-Path -LiteralPath $Pcap)) { throw "PCAP does not exist: $Pcap" }

packetsafari investigate $Pcap --goal security --workflow fast --format json --quiet |
  Set-Content -LiteralPath $Output -Encoding utf8

Get-Content -Raw -LiteralPath $Output | ConvertFrom-Json | Out-Null
Write-Host "Saved $Output"

Operational rules

• Give each integration its own expiring API key.
• Keep the key out of arguments, logs, repository files, and generated reports.
• Treat HTTP acceptance as a receipt, not a completed or verified finding.
• Persist the capture ID, investigation ID, requested settings, and final lifecycle status.
• Retry observation and download independently from submission.
• Check verificationStatus, securityScan, and report maturity before automating an action.
• Use --verify or --workflow progressive when the decision requires more than a preliminary Fast Report.

For directory watchers and resumable uploads, use ingest. For direct HTTP integration, use the Investigations API.