airbyte-agent

airbyte-agent

[!NOTE] Requires the airbyte-agent CLI on PATH. Prefer brew install airbytehq/tap/airbyte-agent-cli. For other platforms, follow the project README: download the installer or release artifact to a file, inspect it, verify any published checksum/signature, and obtain explicit user approval before executing it. Never pipe a remote response directly into a shell.

The CLI is invoked as airbyte-agent <resource> <operation>. It exposes Airbyte's data plane through a uniform interface — every command takes a JSON payload and returns JSON.

[!IMPORTANT] Before running any airbyte-agent command, open the matching reference under references/ and read it first. This top-level file only carries cross-command rules; the per-command syntax, required parameters, response shape, error recovery, and "do NOT" guidance live in each references/<command>.md. Skipping the reference leads to guessed parameter names, missing required fields, and avoidable round-trips — read it even for commands you think you know.

Universal rules (apply to every command)

[!IMPORTANT] Always pass parameters as --json '{...}'. The CLI also exposes per-parameter flags (--workspace, --name, etc.) for human use, but agents should always send a single JSON payload. The two modes are mutually exclusive and JSON keeps your input self-describing for review and replay.

• workspace defaults to "default" when omitted. The CLI prints a JSON notice on stderr when the fallback engages, then proceeds with the API call. Override per-call with "workspace": "..." in the JSON payload, or set a session-wide default via workspaces use.
• --fields trims the response client-side. When you know which fields you need, always pass it. List responses are wrapped in {"data": [...]} and the CLI auto-broadcasts row-level paths: --fields id,name is equivalent to --fields data.id,data.name. If you mix top-level and row-level paths (e.g. include the cursor), use the explicit dotted form for the row-level fields: --fields data.id,next.
• Auth errors (exit 2) mean credentials are missing, invalid, or expired — run airbyte-agent login to refresh, then retry.
• @filename loads JSON from a file — useful when the payload is large or you want to keep the shell command short: --json @params.json.
• Never accept credentials in chat. Two browser flows handle every credential entry path: airbyte-agent login (CLI account credentials) and connectors create (per-connector secrets). If a user offers credentials in conversation, decline and start the appropriate flow.