Connectors CLI Reference

Use chainabit connectors when you want the shortest path from the catalog to a working instance.

Install and Explore

chainabit connectors list
chainabit connectors list --category productivity
chainabit connectors list --active --locale tr
chainabit connectors get slack
chainabit connectors install slack --name "My Slack" --scope personal

connectors list shows the catalog. connectors install defaults to a personally owned connection. Use --scope personal explicitly in scripts. --scope team requires an activated Business account and an owner or admin of the active workspace. A Business account remains Business with one member.

Personal connections are managed by their owner. Workspace connections are managed by an owner or admin of their owning Business workspace. Plan access and live workspace access are also required. Personal connections appear in a Business workspace only when its administrator permits personal use and the connection owner explicitly allows that workspace. Switching workspaces changes the available connections; knowing a connection ID grants no access.

Ownership and workspace selection

Personal workspaces expose My connections only. Team connections always belong to the active Business workspace. Personal and workspace connections remain separate even when they use the same provider.

An explicit automation grant covers an exact connection, agent or chain, tool subset, and output audience. Personal output stays private to its owner by default. Revoking a grant prevents future use; it does not withdraw output already explicitly shared with the workspace.

Chao Tool Access and explicit connections

The CLI reads and changes the server-owned Tool Access preference:

chainabit connectors settings
chainabit connectors settings on_demand
chainabit connectors settings eager

Use an exact connected instance for a Chao turn instead of relying on a generic connector name:

chainabit chao --message "List Company Drive files" \
  --connector <connection-id> --tool-access on_demand

--tool-access is a one-turn override. It does not create CLI-local connector configuration. If the runtime returns a connection, reconnect, selection, or agent-attachment requirement, complete the requested connector action and resume through the server contract; do not substitute another connector.

Example JSON output from connectors list --json:

[
  {
    "key": "slack",
    "displayName": "Slack",
    "category": "communication",
    "authType": "oauth2",
    "supportedFeatures": ["tool_discovery", "health_check"],
    "isActive": true
  }
]

Authenticate an Instance

Browser-based connectors use the default OAuth flow:

chainabit connectors auth inst_123

This path is interactive. In CI or other non-interactive jobs, use a typed credential flag if the connector supports one.

If your connector uses an API key, bearer token, connection string, basic auth, or custom credential payload, pass the typed flag instead:

chainabit connectors auth inst_123 --api-key-env SLACK_API_KEY
chainabit connectors auth inst_123 --token-file ./.secrets/github-token.txt
chainabit connectors auth inst_123 --connection-string-env ANALYTICS_DB_URL
chainabit connectors auth inst_123 --username api-user --password-env CONNECTOR_PASSWORD
chainabit connectors auth inst_123 --custom-file ./.secrets/custom-credentials.json

Use --no-open if you want to copy the OAuth URL manually instead of launching a browser automatically.

Avoid passing connector secrets directly on the command line when possible. Env, stdin, and file-based inputs reduce exposure in shell history and process listings.

Inspect Runtime State

chainabit connectors instances list --scope personal
chainabit connectors instances get inst_123
chainabit connectors instances update inst_123 --name "Team Slack" --enabled
chainabit connectors test inst_123
chainabit connectors tools inst_123 --locale tr

connectors tools shows the tool ids you can execute. The current CLI has no command for connector execution history; use the result returned by connectors exec or the product UI when you need to inspect a completed invocation.

Execute a Tool

chainabit connectors exec inst_123 list_channels \
  --input '{"limit":20}'

connectors exec accepts either the tool key or the tool id shown by connectors tools.

connectors exec runs only tools that do not require approval. A tool that requires approval, such as Slack send_message, is refused with 403 and error code connector_tool_approval_required, and nothing is sent to the external service. Ask Chao to run it instead, which applies its approval rules before acting.

Sync Dynamic Connectors

chainabit connectors sync inst_123

Use sync after connecting to a dynamic MCP-style connector so the CLI and API can refresh the tool list.

JSON Scripting

chainabit connectors list --json | jq '.[0].key'
chainabit connectors tools inst_123 --json

Suggested Workflow

1. chainabit connectors list
2. chainabit connectors install <key>
3. chainabit connectors auth <instance-id>
4. chainabit connectors test <instance-id>
5. chainabit connectors tools <instance-id>
6. chainabit connectors exec <instance-id> <tool> --input '<json>'

Related API Contracts

• Use Connector Instances API for the request and response DTOs behind install, instances, and test.
• Use Connector Tools API for the schemas returned by tools and sync.
• Use Execute Tool API for the input and output contract behind connectors exec.