Terminal
Terminal/Skill
Lets your agent run the airbyte-agent CLI to list, read, and write data in connected SaaS apps like HubSpot and Slack.
By Airbyte
Works with
npx skills add airbytehq/airbyte-agent-cli --skill airbyte-agent[!NOTE] Requires the
airbyte-agentCLI onPATH. Install viabrew install airbytehq/tap/airbyte-agent-cliorcurl -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-agentcommand, open the matching reference underreferences/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 eachreferences/<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.
[!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.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.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.[!IMPORTANT] Always inspect and read skill docs before the first
executeon an unfamiliar connector. Runconnectors inspect, then pass the returneddocs_skill_idtoskills docsfor the outline and exact section you need. Entity names, actions, and params are connector-specific — guessing wastes API calls. Openreferences/connectors-inspect.mdandreferences/skills-docs.mdwhen starting work on a new connector.
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.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.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.connectors describe remains for compatibility only. Use connectors inspect plus skills docs for new workflows.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 |
# 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": {}
}'
| 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) |