# 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
brew install slingdata-io/sling/sling
```

{% endtab %}

{% tab title="Linux" %}

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

{% endtab %}

{% tab title="Windows" %}

```powershell
scoop install sling
```

{% endtab %}
{% endtabs %}

## Quick Start

### 1. Configure a Connection

See the [Environment documentation](https://docs.slingdata.io/sling-cli/environment) 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](https://docs.slingdata.io/concepts/api-specs)
3. Use `api-spec-tester` to validate and debug
4. Generate a [replication](https://docs.slingdata.io/concepts/replication) 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](https://docs.slingdata.io/concepts/replication) YAML with [incremental settings](https://docs.slingdata.io/concepts/replication/modes).

## Slash Commands (Claude Code)

Slash commands provide direct access to Sling CLI operations:

### /sling:run

Execute a [replication](https://docs.slingdata.io/concepts/replication) or [pipeline](https://docs.slingdata.io/concepts/pipeline) 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](https://docs.slingdata.io/concepts/api-specs) YAML files from research findings.

**Example:**

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

**Outputs:**

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

### 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](https://docs.slingdata.io/concepts/pipeline) 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](https://docs.slingdata.io/concepts/pipeline) YAML with sequential steps
* [Hook](https://docs.slingdata.io/concepts/hooks) 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](https://docs.slingdata.io/sling-cli/environment)      |
| `sling-replications`    | "replication", "sync", "copy" | [Data movement configs](https://docs.slingdata.io/concepts/replication)       |
| `sling-pipelines`       | "pipeline", "workflow"        | [Multi-step orchestration](https://docs.slingdata.io/concepts/pipeline)       |
| `sling-transforms`      | "transform", "convert"        | [Data transformation functions](https://docs.slingdata.io/concepts/functions) |
| `sling-hooks`           | "hook", "before", "after"     | [Pre/post actions](https://docs.slingdata.io/concepts/hooks)                  |
| `sling-troubleshooting` | "error", "debug", "fix"       | Error diagnosis                                                               |
| `sling-api-specs`       | "api spec", "rest api"        | [API specification building](https://docs.slingdata.io/concepts/api-specs)    |

**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](https://docs.slingdata.io/concepts/hooks) (http, sql, check, command)
* Placement options (pre/post replication)
* Configuration examples
* [Variable access](https://docs.slingdata.io/concepts/replication/runtime-variables) 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](https://docs.slingdata.io/concepts/api-specs) 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](https://docs.slingdata.io/connections/database-connections/postgres) to [Snowflake](https://docs.slingdata.io/connections/database-connections/snowflake). See [database-to-database examples](https://docs.slingdata.io/examples/database-to-database).

**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](https://docs.slingdata.io/concepts/replication/modes) and [incremental examples](https://docs.slingdata.io/examples/database-to-database/incremental).

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](https://docs.slingdata.io/concepts/pipeline) that syncs data, validates it, and sends notifications. See [pipeline examples](https://docs.slingdata.io/concepts/pipeline/examples).

**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](https://docs.slingdata.io/concepts/hooks/replication)
* [SQL check hook](https://docs.slingdata.io/concepts/hooks/check)
* [HTTP webhook](https://docs.slingdata.io/concepts/hooks/http) for Slack
* [HTTP webhook](https://docs.slingdata.io/concepts/hooks/http) 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](https://docs.slingdata.io/sling-cli/ai/mcp).

### connection

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

**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](https://docs.slingdata.io/connections/file-connections)
* `inspect` - Get file metadata

### replication

Manage [replications](https://docs.slingdata.io/concepts/replication).

**Actions:**

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

### pipeline

Manage [pipelines](https://docs.slingdata.io/concepts/pipeline).

**Actions:**

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

### api\_spec

Work with [API specifications](https://docs.slingdata.io/concepts/api-specs).

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