kiln

What this skill does

# 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** | 114 CLI commands | 430 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 --json

# Run safety checks before printing
kiln preflight --json
kiln preflight --material PLA --json

# Upload a G-code file
kiln upload /path/to/model.gcode --json

# Start printing (auto-uploads local files, auto-runs preflight)
kiln print model.gcode --json
kiln print model.gcode --dry-run --json   # preview without starting

# Cancel / pause / resume
kiln cancel --json
kiln pause --json
kiln resume --json

# Set temperatures
kiln temp --tool 210 --bed 60 --json
kiln temp --json                        # read current temps (no flags)

# Send raw G-code
kiln gcode G28 "G1 X50 Y50 F3000" --json

# Slice STL to G-code
kiln slice model.stl --json
kiln slice model.stl --print-after --json   # slice + upload + print

# Webcam snapshot
kiln snapshot --save photo.jpg --json

# Wait for print to finish (blocks until done)
kiln wait --json

# Print history
kiln history --json
kiln history --status completed --json

# Discover printers on network
kiln discover --json

# Cost estimate
kiln cost model.gcode --json
```

### Outsourced Manufacturing (Fulfillment)

No local printer? Printer busy? Kiln can outsource to manufacturing
services (Craftcloud, Sculpteo) with the same CLI.

```bash
# List available materials from configured service
kiln order materials --json

# Get a manufacturing quote (uploads model, returns pricing + lead time)
kiln order quote model.stl -m pla_standard --json

# Place the order [confirm — ask human first, shows price]
kiln order place QUOTE_ID --json

# Track order status
kiln order status ORDER_ID --json

# Cancel (if still cancellable)
kiln order cancel ORDER_ID --json

# Compare local printing vs. outsourced cost side-by-side
kiln compare-cost model.gcode --fulfillment-material pla_standard --json
```

**Setup:** Set one of these env vars (or add to `~/.kiln/config.yaml`):
```bash
export KILN_CRAFTCLOUD_API_KEY="your_key"     # Craftcloud (easiest — one key)
# OR
export KILN_SCULPTEO_API_KEY="your_key"       # Sculpteo
```

**Agent workflow:** Check local printer → if unavailable/busy → quote
fulfillment → present price to human → human approves → place order →
return tracking link.

### Text & Sketch to 3D Generation

Generate printable 3D models from text descriptions or napkin sketches.
Kiln auto-discovers providers from environment variables.

```bash
# List available generation providers [safe]
kiln generate list --json

# Generate a model from text [confirm — creates new file]
kiln generate "a small vase with organic curves" --provider gemini --json
kiln generate "phone stand" --provider meshy --style organic --json

# Check generation status (for async providers like Meshy/Tripo3D)
kiln generate status JOB_ID --json

# Download completed result
kiln generate download JOB_ID --json
```

**MCP equivalents:**
```json
{"name": "list_generation_providers", "arguments": {}}
{"name": "generate_model", "arguments": {"prompt": "a small vase", "provider": "gemini"}}
{"name": "check_generation_status", "arguments": {"job_id": "gemini-abc123"}}
{"name": "download_generated_model", "arguments": {"job_id": "gemini-abc123"}}
```

**Available providers** (set env var to enable):

| Provider | Env Var | Type | Async? |
|----------|---------|------|--------|
| **Gemini Deep Think** | `KILN_GEMINI_API_KEY` | AI reasoning → OpenSCAD → STL | No (synchronous) |
| **Meshy** | `KILN_MESHY_API_KEY` | Cloud text-to-3D | Yes (poll status) |
| **Tripo3D** | `KILN_TRIPO3D_API_KEY` | Cloud text-to-3D | Yes (poll status) |
| **Stability AI** | `KILN_STABILITY_API_KEY` | Cloud text-to-3D | Yes (poll status) |
| **OpenSCAD** | (local binary) | Parametric code → STL | No (synchronous) |

**Gemini Deep Think** uses Google's Gemini API to reason about geometry
and generate precise OpenSCAD code, which is compiled locally to STL.
Supports text descriptions and sketch/napkin-drawing descriptions.
Requires OpenSCAD installed locally.

**Agent workflow:** Ask what the user wants → generate with best
available provider → validate mesh → slice → print.

### Model Marketplace Search

Search and download existing 3D models from online marketplaces before
generating from scratch.

```bash
# Search across all connected marketplaces [safe]
kiln search "phone stand" --json

# Search a specific marketplace [safe]
kiln search "vase" --marketplace thingiverse --json

# Get model details [safe]
kiln model-details thingiverse MODEL_ID --json

# Download a model file [confirm — downloads to local disk]
kiln model-download thingiverse MODEL_ID --json
```

**MCP equivalents:**
```json
{"name": "search_all_models", "arguments": {"query": "phone stand"}}
{"name": "search_models", "arguments": {"query": "vase", "marketplace": "thingiverse"}}
{"name": "get_model_details", "arguments": {"marketplace": "thingiverse", "model_id": "12345"}}
{"name": "download_model_file", "arguments": {"marketplace": "thingiverse", "model_id": "12345"}}
```

**Supported marketplaces:** Thingiverse, MyMiniFactory, Thangs,
Cults3D, GrabCAD, Etsy.

**Agent workflow:** User describes what they want → search marketplaces
→ present top results → if nothing fits, generate from text instead.

### Fleet Management

Manage multiple printers as a fleet with job queuing and smart routing.

```bash
# Register a printer in the fleet [guarded]
kiln fleet add --name ender3 --host http://192.168.1.100 --type octoprint --json

# Fleet-wide status [safe]
kiln fleet status --json

# Submit a job to the queue (auto-routes to best available printer)
kiln fleet print model.gcode --json

# View job queue [safe]
kiln fleet queue --json
```

**MCP equivalents:**
```json
{"name": "fleet_status", "arguments": {}}
{"name": "register_printer", "arguments": {"name": "ender3", "host": "http://192.168.1.100", "type": "octoprint"}}
{"name": "submit_fleet_job", "arguments": {"filename": "model.gcode"}}
{"name": "list_queue", "arguments": {}}
```

### Webhooks

Register HTTP endpoints to receive real-time notifications.

```bash
# Register a webhook [guarded]
kiln webhook