kiln

# Kiln — Agent Skill Definition

You are controlling a physical 3D printer through Kiln.
**Physical actions are irreversible and can damage hardware.** Follow
these rules strictly.

## Quick Start

```bash
kiln setup          # interactive wizard — finds printers, saves config
kiln verify         # check everything is working
kiln status --json  # see what the printer is doing
```

Then ask the human what they'd like to print.

---

## Which Interface to Use

Kiln supports **two interfaces**. Pick based on your capabilities:

| | CLI | MCP |
|---|---|---|
| **Use when** | You have a shell/exec tool | You have an MCP client configured |
| **How it works** | `kiln <command> [flags] --json` | MCP tool calls with JSON arguments |
| **Response format** | JSON to stdout (with `--json`) | Structured JSON objects |
| **Setup** | Just env vars + `kiln` on PATH | `kiln serve` running as MCP server |
| **Tool count** | 107 CLI commands | 273 MCP tools |
| **Best for** | Quick start, debugging, simple workflows | Tight integration, full tool catalog |

**Don't know which?** Try CLI first. Run `kiln status --json`. If that
works, you're good. MCP gives you more tools but requires server setup.

---

## CLI Interface

Run commands via your shell/exec tool. **Always use `--json`** for
machine-readable output.

```bash
kiln <command> [options] --json
```

### First-Time Setup

If the printer isn't configured yet, run these first:

```bash
# Interactive wizard: auto-discovers printers, saves config, tests connection
kiln setup

# Or manually add a printer
kiln auth --name my-printer --host http://192.168.1.100 --type octoprint --api-key YOUR_KEY

# Verify everything works (Python, slicer, config, printer reachable, database)
kiln verify

# Scan network for printers
kiln discover --json
```

After setup, config is saved to `~/.kiln/config.yaml` — no env vars needed.

### Core Commands

```bash
# Check printer status (start here)
kiln status --json

# List files on printer
kiln files...