# Working with AI 🤖

Sling CLI integrates seamlessly with AI coding assistants through the **slingdata-ai** plugin, enabling you to research APIs, design data integrations, and debug configurations using natural language—all within your AI assistant. See github repo <https://github.com/slingdata-io/slingdata-ai> for resources.

## Overview

The slingdata-ai plugin provides:

* **Slash commands** for direct execution of replications and pipelines
* **Specialized agents** for complex workflows (API research, spec building, replication design)
* **Skills** that load contextual documentation automatically
* **MCP integration** that connects your AI assistant to Sling CLI tools

**Supported AI Assistants:**

* [Claude Code](https://claude.ai/code) (primary)
* [GitHub Copilot](https://github.com/features/copilot)
* [Google Gemini](https://gemini.google.com/)
* [Cline](https://github.com/cline/cline)
* Other [MCP-compatible assistants](https://modelcontextprotocol.io/)

## Installation

### From Marketplace (Recommended)

If using Claude Code with marketplace support:

```bash
/plugin marketplace add slingdata-io/slingdata-ai
/plugin install sling@slingdata-ai
```

### Local Development

For contributing or local development:

```bash
claude --plugin-dir /path/to/slingdata-ai
```

### Prerequisites

* **Sling CLI v1.5.0+** must be installed
* Connections configured in `~/.sling/env.yaml`
* AI assistant with MCP support

Install Sling CLI:

{% tabs %}
{% tab title="macOS" %}

```bash
curl -fsSL https://slingdata.io/install.sh | bash
```

{% endtab %}

{% tab title="Linux" %}

```bash
curl -fsSL https://slingdata.io/install.sh | bash
```

{% endtab %}

{% tab title="Windows" %}

```powershell
irm https://slingdata.io/install.ps1 | iex
```

{% endtab %}
{% endtabs %}

## Quick Start

### 1. Configure a Connection

See the [Environment documentation](/sling-cli/environment.md) for details on managing connections.

```bash
sling conns set MY_POSTGRES type=postgres host=localhost user=postgres database=mydb
```

### 2. Use Commands in AI Assistant (Claude Code)

List connections:

```
/sling:conns list
```

Test a connection:

```
/sling:conns test MY_POSTGRES
```

Discover tables:

```
/sling:conns discover MY_POSTGRES public.*
```

### 3. Build with Natural Language

Instead of writing YAML manually, describe what you want:

**Example: API Integration**

```
"Research the Stripe API and create a specification for extracting customers and invoices"
```

The AI will:

1. Use the `api-researcher` agent to analyze Stripe's API documentation
2. Invoke `api-spec-builder` to create the YAML [API specification](/concepts/api-specs.md)
3. Use `api-spec-tester` to validate and debug
4. Generate a [replication](/concepts/replication.md) config to sync data to your database

**Example: Database Replication**

```
"Design a replication from MY_POSTGRES to MY_SNOWFLAKE that syncs the public.users and public.orders tables incrementally"
```

The AI will use the `replication-builder` agent to create a proper [replication](/concepts/replication.md) YAML with [incremental settings](/concepts/replication/modes.md).

## Slash Commands (Claude Code)

Slash commands provide direct access to Sling CLI operations:

### /sling:run

Execute a [replication](/concepts/replication.md) or [pipeline](/concepts/pipeline.md) file with validation.

**Usage:**

```
/sling:run /path/to/replication.yaml
/sling:run /path/to/pipeline.yaml
```

The command will:

* Parse and validate the YAML file
* Check connection availability
* Execute the replication or pipeline
* Display progress and results

### /sling:conns

Manage connections interactively.

**List all connections:**

```
/sling:conns list
```

**Test a connection:**

```
/sling:conns test MY_POSTGRES
```

**Discover streams (tables/files/endpoints):**

```
/sling:conns discover MY_POSTGRES
/sling:conns discover MY_POSTGRES public.*
/sling:conns discover MY_S3 data/*.csv
```

## Specialized Agents

Agents are AI sub-processes that handle complex, multi-step tasks autonomously. They have access to specific tools and are optimized for particular workflows.

### API Specification Agents

Build custom REST API connectors through a research → build → test workflow.

#### api-researcher

Research REST API documentation to gather authentication methods, endpoints, pagination patterns, and rate limits.

**Example:**

```
"Use the api-researcher agent to analyze the Shopify Admin API documentation"
```

**Outputs:**

* Authentication type and credentials needed
* Available endpoints and their purposes
* Pagination strategy (cursor, offset, page-based)
* Rate limit information

#### api-spec-builder

Create Sling [API specification](/concepts/api-specs.md) YAML files from research findings.

**Example:**

```
"Build an API spec for Shopify with orders, customers, and products endpoints"
```

**Outputs:**

* Complete `shopify.yaml` specification
* [Authentication](/concepts/api-specs/authentication.md) configuration
* Endpoint definitions with [pagination](/concepts/api-specs/request.md)
* [Response processors](/concepts/api-specs/response.md)

### Data Integration Agents

#### replication-builder

Design replication configurations for moving data between databases, files, and APIs.

**Example:**

```
"Create a replication from MY_POSTGRES to MY_SNOWFLAKE for the sales schema"
```

**Outputs:**

* Replication YAML with proper modes (full-refresh vs incremental)
* Stream selection and transformations
* Performance optimizations

#### pipeline-builder

Design multi-step data [workflows](/concepts/pipeline.md) with validation, transformations, and notifications.

**Example:**

```
"Create a pipeline that:
1. Syncs data from Stripe to Postgres
2. Runs a dbt transformation
3. Sends a Slack notification on completion"
```

**Outputs:**

* [Pipeline](/concepts/pipeline.md) YAML with sequential steps
* [Hook](/concepts/hooks.md) configurations for notifications
* Error handling and retries

## Skills

Skills are topic-specific documentation modules that load automatically based on keywords in your conversation. They provide contextual guidance without requiring explicit invocation.

### Available Skills

| Skill                   | Triggers                      | Purpose                                                 |
| ----------------------- | ----------------------------- | ------------------------------------------------------- |
| `sling`                 | "sling", "data integration"   | Platform overview and tools                             |
| `sling-connections`     | "connection", "connect to"    | [Connection management](/sling-cli/environment.md)      |
| `sling-replications`    | "replication", "sync", "copy" | [Data movement configs](/concepts/replication.md)       |
| `sling-pipelines`       | "pipeline", "workflow"        | [Multi-step orchestration](/concepts/pipeline.md)       |
| `sling-transforms`      | "transform", "convert"        | [Data transformation functions](/concepts/functions.md) |
| `sling-hooks`           | "hook", "before", "after"     | [Pre/post actions](/concepts/hooks.md)                  |
| `sling-troubleshooting` | "error", "debug", "fix"       | Error diagnosis                                         |
| `sling-api-specs`       | "api spec", "rest api"        | [API specification building](/concepts/api-specs.md)    |

**Example:**

When you ask:

```
"How do I add a webhook notification after my replication completes?"
```

The `sling-hooks` skill automatically loads, providing context about:

* [Hook types](/concepts/hooks.md) (http, sql, check, command)
* Placement options (pre/post replication)
* Configuration examples
* [Variable access](/concepts/replication/runtime-variables.md) in hooks

## Common Workflows

### Building a Custom API Connector

**Goal:** Extract data from a REST API that Sling doesn't natively support. See the [API Specifications concept guide](/concepts/api-specs.md) for detailed information.

**Steps:**

1. **Research the API**

```
"Research the Zendesk API focusing on tickets, users, and organizations endpoints"
```

→ Uses `api-researcher` agent

2. **Build the specification**

```
"Create a Zendesk API spec with OAuth2 authentication and the endpoints we researched"
```

→ Uses `api-spec-builder` agent

3. **Test the spec**

```
/sling:conns set MY_ZENDESK type=api spec=zendesk secrets='{ client_id: xxx, client_secret: xxx }'
/sling:conns test MY_ZENDESK
```

→ Uses `api-spec-tester` agent if issues arise

4. **Create replication**

```
"Create a replication from MY_ZENDESK to MY_POSTGRES"
```

→ Uses `replication-builder` agent

5. **Execute**

```
/sling:run zendesk-replication.yaml
```

### Database Migration

**Goal:** Migrate a database from [Postgres](/connections/database-connections/postgres.md) to [Snowflake](/connections/database-connections/snowflake.md). See [database-to-database examples](/examples/database-to-database.md).

**Steps:**

1. **Set up connections**

```
/sling:conns test MY_POSTGRES
/sling:conns test MY_SNOWFLAKE
```

2. **Design replication**

```
"Create a replication from MY_POSTGRES to MY_SNOWFLAKE for all tables in the public schema with incremental sync where possible"
```

See [replication modes](/concepts/replication/modes.md) and [incremental examples](/examples/database-to-database/incremental.md).

3. **Review and adjust** The AI generates a replication YAML. You can refine:

```
"Exclude the public.logs table and use full-refresh for public.dim_products"
```

4. **Execute**

```
/sling:run pg-to-snowflake.yaml
```

### ETL Pipeline with Validation

**Goal:** Build a [pipeline](/concepts/pipeline.md) that syncs data, validates it, and sends notifications. See [pipeline examples](/concepts/pipeline/examples.md).

**Steps:**

1. **Describe the pipeline**

```
"Create a pipeline that:
- Syncs Stripe charges to MY_POSTGRES
- Runs a SQL check that revenue is > 0
- Sends a Slack webhook on success
- Sends an email alert on failure"
```

2. **Review generated YAML** The `pipeline-builder` agent creates a pipeline with:

* [Replication step](/concepts/hooks/replication.md)
* [SQL check hook](/concepts/hooks/check.md)
* [HTTP webhook](/concepts/hooks/http.md) for Slack
* [HTTP webhook](/concepts/hooks/http.md) for email alerts

3. **Execute**

```
/sling:run stripe-validation-pipeline.yaml
```

## MCP Tools Reference

The plugin communicates with Sling CLI through [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) tools. These are invoked automatically by the AI but understanding them helps debug issues.

For detailed information about the MCP server, configuration options, and using Sling MCP with other AI assistants ([Claude Desktop](https://claude.ai/download), [VSCode Copilot](https://code.visualstudio.com/docs/copilot/overview), ChatGPT), see the [MCP Server documentation](/sling-cli/ai/mcp.md).

### connection

Manage [connections](/sling-cli/environment.md) (list, test, discover, set). See [database connections](/connections/database-connections.md), [storage connections](/connections/file-connections.md), and [API connections](/connections/api-connections.md).

**Actions:**

* `list` - Show all connections
* `test` - Test connection validity
* `discover` - List streams (tables/files/endpoints)
* `set` - Create or update connection

### database

Query databases and retrieve metadata.

**Actions:**

* `query` - Execute SELECT queries
* `get_schemata` - Get schema/table/column metadata
* `get_columns` - Get column details

### file\_system

List, copy, and inspect files.

**Actions:**

* `list` - List files/directories
* `copy` - Copy between [storage connections](/connections/file-connections.md)
* `inspect` - Get file metadata

### replication

Manage [replications](/concepts/replication.md).

**Actions:**

* `parse` - Validate YAML syntax
* `compile` - Full validation
* `run` - Execute replication

### pipeline

Manage [pipelines](/concepts/pipeline.md).

**Actions:**

* `parse` - Validate YAML syntax
* `run` - Execute pipeline

### api\_spec

Work with [API specifications](/concepts/api-specs.md).

**Actions:**

* `parse` - Load and validate spec
* `test` - Test API endpoints

## Troubleshooting

### Plugin Not Loading

**Check installation:**

```bash
claude plugin list
```

You should see `sling@slingdata-ai` in the list.

**Verify Sling CLI:**

```bash
sling --version
```

Should return v1.5.0 or higher.

### MCP Connection Issues

**Check MCP server status:** The plugin uses `sling mcp` as the MCP server. Test it:

```bash
sling mcp
```

Should start an MCP server on stdio.

**Configuration location:** `.mcp.json` in the plugin directory configures the server.

**For more MCP troubleshooting:** See the [MCP Server troubleshooting section](/sling-cli/ai/mcp.md#troubleshooting) for log locations, debug output, and detailed diagnostics.

### Commands Not Working

**Check syntax:**

```
# Correct
/sling:run /path/to/file.yaml

# Incorrect
/sling run /path/to/file.yaml  (missing colon)
```

**Check file paths:** Use absolute paths or paths relative to current working directory.

### Agent Failures

**Enable debug mode:** When testing connections or API specs, add debug flag:

```
/sling:conns test MY_API --debug
```

**Check credentials:** Verify secrets in `~/.sling/env.yaml`:

```yaml
connections:
  MY_API:
    type: api
    spec: my_spec
    secrets:
      api_key: ${API_KEY}  # Must be set in environment
```

**Review agent output:** Agents provide detailed error messages. Look for:

* Authentication failures (401/403)
* Rate limit errors (429)
* Invalid endpoints (404)
* Malformed requests (400)

## Best Practices

### Use Natural Language First

Instead of manually writing YAML, describe what you want:

```
"Sync PostgreSQL users table to Snowflake incrementally using updated_at column"
```

The AI will generate proper configuration and explain design decisions.

### Iterate with Agents

For complex tasks, work step-by-step with agents:

1. Research (api-researcher)
2. Cross-reference (api-cross-referencer)
3. Build (api-spec-builder)
4. Test (api-spec-tester)

Each agent focuses on its specialty, improving quality.

### Use Skills for Learning

Skills auto-load based on keywords. To learn about a topic, ask questions:

```
"What transformation functions are available?"  → loads sling-transforms skill (see [Functions](../concepts/functions.md))
"How do I handle errors in pipelines?"          → loads sling-hooks skill (see [Hooks](../concepts/hooks.md))
"How do I set up OAuth2 for an API?"            → loads sling-api-specs skill (see [Authentication](../concepts/api/authentication.md))
```

## What's Next?

* [MCP Server](/sling-cli/ai/mcp.md) - Use Sling with [Claude Desktop](https://claude.ai/download), [VSCode Copilot](https://code.visualstudio.com/docs/copilot/overview), and other AI assistants
* [Environment Setup](/sling-cli/environment.md) - Configure connections and credentials
* [Replications](/concepts/replication.md) - Deep dive into replication configs
* [Pipelines](/concepts/pipeline.md) - Build multi-step workflows
* [API Specifications](/concepts/api-specs.md) - Create custom API connectors
* [Hooks](/concepts/hooks.md) - Add pre/post actions


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/sling-cli/ai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.