> For the complete documentation index, see [llms.txt](https://docs.slingdata.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.slingdata.io/sling-cli/ai/assist.md).

# Sling Assist

Get AI help locally to build, run and debug replications, pipelines, API Specs, etc.

`sling assist` installs Sling skills and MCP into your local AI agent. After setup, it launches your preffered local AI to help you build, run and debug replications, pipelines, API Specs, etc, by automatically providing useful context.

## Quick start

```bash
sling assist                     # first run: setup; after: greet with choices
sling assist "backfill orders"   # positional ask (skip the card, launch)
sling assist --id <id>           # investigate a failed run
sling assist --resume            # pick a past session
sling assist --resume <id>       # resume that session
sling assist setup               # re-run setup / change agent
sling assist setup --doctor      # health report
sling assist error <sig>         # look up an error signature
sling assist report --id <id>    # review a redacted failure report
sling assist --out -             # print the prompt, do not launch
sling assist --agent claude      # one-run agent override
sling assist --model sonnet      # pass --model to the agent
```

## First run

If no profile exists, `sling assist` runs setup.

1. Detect CLI agents on `$PATH` (`claude`, `codex`, `gemini`, `cursor`, `opencode`, `pi`, `grok`). VS Code is an install target, not a launchable agent.
2. Rank the detected agents. Sling prefers the one that is signed in.
3. Write the profile to `~/.sling/env.yaml` under `env.SLING_ASSIST`.
4. Write skills to `~/.agents/skills/` and wire each detected client.

`sling assist setup --doctor` lists only agents on `$PATH`. A missing binary is not a failure.

{% hint style="warning" %}
You need at least one CLI agent on `$PATH`, or you can let Sling install OpenCode.
{% endhint %}

After setup, verify:

```bash
sling assist setup --doctor
```

To change the agent or scope later, run `sling assist setup`.

Each `sling assist` call refreshes the skill bundle for wired clients. The refresh also removes retired skills. If no skills are installed, the refresh does not install them. Run `sling assist setup` first.

## Daily use

After setup, `sling assist` with no ask prints a card and waits. It does not launch an agent until you pick an option or type an ask.

### Ask

Pass an ask to skip the card and launch:

```bash
sling assist "create a replication from postgres to snowflake"
sling assist "add an incremental stream for orders"
```

The ask is a trailing argument. `--name` sets the history slug. Default is a slug from the ask, or `assist`.

### Investigate a failed run

```bash
sling assist --id 3f9c2a10
```

After a failure, Sling prints a hint line with the short exec id:

```
  investigate with AI -> sling assist --id 3f9c2a10
```

`--id` accepts any unique id prefix. It loads that failure snapshot, adds the error signature, the sanitized error excerpt, and the run log tail to the prompt, then launches the agent.

Set `SLING_ASSIST_HINT=false` to suppress the hint line, or set `hint_in_errors: false` in the profile.

Failure snapshots live under `~/.sling/assist/errors/executions/`. Sling keeps at most 100.

{% hint style="info" %}
`sling assist --id` assembles a prompt from the failure snapshot and launches a CLI agent — it does **not** itself write a report file to a fixed path or format. To emit the prompt to a file instead of launching, use `--out <path>` (or `--out -` for stdout). To produce a shareable, redacted failure report, use [`sling assist report --id <id>`](#subcommands).
{% endhint %}

### Agent and model

```bash
sling assist --agent grok --model grok-4
sling assist --resume --model sonnet
```

`--agent` and `--model` apply to this run only. An empty `--model` uses the agent default. Sling does not rewrite aliases. The agent validates the name.

Cursor uses the `agent` binary, not `cursor`.

### Print the prompt

```bash
sling assist --out -                          # stdout
sling assist --out /tmp/prompt.md "backfill orders"
```

`--out -` prints to stdout. Any other value is a file path.

If you already run inside Claude Code, Cursor, or OpenCode, Sling prints the prompt. It does not launch a nested agent. The same applies off a TTY. Those paths do not show the open screen.

`--non-interactive` skips interactive forms and launches in headless mode. You must pass an ask or `--id`. With neither, Sling exits with an error.

## Flags on `sling assist`

| Flag                | Description                                                           |
| ------------------- | --------------------------------------------------------------------- |
| `--id`              | Investigate a failure by its id. An id prefix works.                  |
| `--resume [id]`     | Resume a past session. Omit the id to pick.                           |
| `--agent`           | Override the profile agent for this run only.                         |
| `--model`           | Pass `--model` to the agent for this run only.                        |
| `--name`            | History slug override.                                                |
| `--out`, `-o`       | Emit the prompt instead of launching: a file path, or `-` for stdout. |
| `--non-interactive` | Skip forms. Launch headless. Requires an ask or `--id`.               |

Pass the ask as a trailing argument.

## Subcommands

| Command                         | Description                                        |
| ------------------------------- | -------------------------------------------------- |
| `sling assist setup`            | Install skills and MCP, or reconfigure / uninstall |
| `sling assist error <sig>`      | Look up guidance for an error signature            |
| `sling assist report --id <id>` | Compose a redacted issue report from a failed run  |

## Supported agents

| Agent      | Launch     | Notes                                          |
| ---------- | ---------- | ---------------------------------------------- |
| `claude`   | `claude`   | Claude Code CLI                                |
| `codex`    | `codex`    | OpenAI Codex CLI                               |
| `gemini`   | `gemini`   | Gemini CLI                                     |
| `cursor`   | `agent`    | Cursor CLI (`agent`, not `cursor`)             |
| `opencode` | `opencode` | OpenCode. Sling can install this as a fallback |
| `pi`       | `pi`       | Pi agent                                       |
| `grok`     | `grok`     | Grok CLI                                       |
| `vscode`   | —          | Skills + MCP only. Not a launchable CLI agent  |

## Skills

Setup writes these skills to `~/.agents/skills/`:

| Skill                | Covers                                 |
| -------------------- | -------------------------------------- |
| `sling`              | Sling CLI overview and routing         |
| `sling-replications` | Replication configs                    |
| `sling-pipelines`    | Pipeline configs and hooks             |
| `sling-build`        | SQL models and `sling build`           |
| `sling-api-specs`    | API spec authoring                     |
| `sling-platform`     | Platform commands and the platform MCP |
| `sling-python`       | The Python wrapper                     |
| `agent-browser`      | Browser control for API research       |

Each client gets a redirect file that points into `~/.agents/skills/`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.