airbyte-agent

airbyte-agent

[!NOTE] Requires the airbyte-agent CLI on PATH. Install via brew install airbytehq/tap/airbyte-agent-cli or curl -fsSL https://airbyte.ai/install.sh | bash. See the project README for other options.

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. connectors execute keeps its action payload under result, so use paths such as result.data.id,result.meta,warning; read its reference for details. Empty arrays count as matches once their prefix resolves. If no requested path matches, the CLI returns a validation error instead of {} and preserves the already-completed response under detail.response; do not re-run a write solely to fix its projection.
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.

Connector rules (apply to every connector workflow)

[!IMPORTANT] Always inspect and read skill docs before the first execute on an unfamiliar connector. Run connectors inspect, then pass the returned docs_skill_id to skills docs for the outline and exact section you need. Entity names, actions, and params are connector-specific — guessing wastes API calls. Open references/connectors-inspect.md and references/skills-docs.md when starting work on a new connector.

On connectors execute, field selection is MANDATORY. Every call must include select_fields (allowlist) or exclude_fields (blocklist) inside the JSON payload, in addition to any --fields you pass.
For Context Store reads, follow the execution guidance in skills docs. It names the default Context Store read action for this connector and documents its exact parameters. Do not hard-code an action or substitute another action based on local assumptions.
Connector name resolution. Most commands accept name (case-insensitive match against connector instance name, template display name, or template slug) OR id (UUID). Pass id when two connectors share a name.
Legacy describe. connectors describe remains for compatibility only. Use connectors inspect plus skills docs for new workflows.

Command index — read the matching reference before running

Each row points to the per-command playbook with usage, workflows, error recovery, and "do NOT" guidance. Open the reference first, then compose the command. If the user's task spans multiple commands (e.g. discover workspace → inspect connector → read docs → execute), read each reference as you reach that step.

User wants to…	Reference
Run an action (list/get/search/create/update) against connector data — the workhorse	`references/connectors-execute.md`
Inspect connector metadata, readiness, warnings, and `docs_skill_id`	`references/connectors-inspect.md`
List available connector and static skill docs	`references/skills-list.md`
Search skill docs by task or connector	`references/skills-search.md`
Read usage docs by `docs_skill_id` and exact section	`references/skills-docs.md`
Use the legacy connector schema describe command	`references/connectors-describe.md`
Install a new connector via the browser credential flow	`references/connectors-create.md`
Re-enter or fix credentials for an existing connector via the browser	`references/connectors-update.md`
Delete a connector (destructive — confirm first)	`references/connectors-delete.md`
List connectors configured in a workspace	`references/connectors-list.md`
List connector templates available to install	`references/connectors-list-available.md`
List workspaces (usually the first command in a session)	`references/workspaces-list.md`
Set the default workspace in `~/.airbyte-agent/settings.json`	`references/workspaces-use.md`
List organizations the authenticated user belongs to	`references/organizations-list.md`
Set the default organization in `~/.airbyte-agent/settings.json`	`references/organizations-use.md`
Print the merged CLI + OpenAPI schema for any operation	`references/schema.md`

Typical session shape

# 1. Discover the environment
airbyte-agent workspaces list
airbyte-agent connectors list --json '{"workspace": "<name>"}'

# 2. Learn the connector
airbyte-agent connectors inspect --json '{"workspace": "<name>", "name": "<connector>"}'
airbyte-agent skills docs --json '{"id": "<docs_skill_id from inspect>"}' --fields data.markdown
airbyte-agent skills docs --json '{"id": "<docs_skill_id from inspect>", "section": "<exact-section-id>"}' --fields data.markdown

# 3. Read data using the default action and exact params named in skills docs.
# Values in angle brackets are placeholders. Replace the empty params object in
# full with the exact object from skills docs; do not execute placeholders.
airbyte-agent connectors execute --json '{
  "workspace": "<name>",
  "name": "<connector>",
  "entity": "<from-skills-docs>",
  "action": "<default-context-store-read-action-from-skills-docs>",
  "select_fields": ["<field-from-skills-docs>"],
  "params": {}
}'

Exit codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Authentication error → run `airbyte-agent login`
`3`	Not found (workspace, connector, template, entity…)
`4`	Validation error (bad params, ambiguous name, missing confirmation)