airbyte-agent

name	airbyte-agent
description	Drive the `airbyte-agent` CLI to manage Airbyte connectors, workspaces, and organizations. Run list/get/search/create/update actions against connector data (HubSpot, Salesforce, Slack, GitHub, etc.), install new connectors via the browser credential flow, list and switch workspaces, list organizations, inspect connector metadata, read skill docs, or print the merged CLI + OpenAPI schema for any operation. Use when the user mentions Airbyte, the `airbyte-agent` CLI, connectors, syncs, workspaces, organizations, or asks to read/write data from a connected SaaS product.
metadata	{"version":"v0.1.2"}

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. 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.

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.
• Prefer context_store_search over list for reads. Search supports rich filters, sorting, and pagination; list is the live source — use it only when the search index might lag (today's data) or when search returns empty.
• 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

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
airbyte-agent connectors execute --json '{
  "workspace": "<name>",
  "name": "<connector>",
  "entity": "<from-skills-docs>",
  "action": "context_store_search",
  "select_fields": ["..."],
  "params": {"limit": 20, "query": {"filter": {...}}}
}'

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)