Kiln

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.

kiln <command> [options] --json

First-Time Setup

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

# 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

# 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.

# 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):

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.

# 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:

{"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):

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.

# 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:

{"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.

# 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:

{"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.

# Register a webhook [guarded]
kiln webhook add https://example.com/hook --events print_complete,print_failed --json

# List webhooks [safe]
kiln webhook list --json

# Delete a webhook [confirm]
kiln webhook delete WEBHOOK_ID --json

All payloads are signed with HMAC-SHA256 for verification.

Multi-Printer Support

# List saved printers
kiln printers --json

# Target a specific printer (works with any command)
kiln --printer my-ender3 status --json
kiln --printer bambu-x1c print model.gcode --json

Run kiln --help for all commands. kiln <command> --help for options.

CLI Response Format

Success — exit code 0, JSON to stdout:

{"status": "printing", "filename": "model.gcode", "progress": 42.5,
 "temps": {"tool": 210.0, "bed": 60.0}}

Error — non-zero exit code, JSON with "error":

{"error": "Printer is offline"}

Warnings — "warnings" array alongside normal data:

{"status": "ok", "warnings": ["Hotend temperature above typical PLA range"]}

Check exit code first (0 = success), then "warnings" in the JSON.

Example Responses

kiln status --json (printing):

{"status": "success", "data": {"printer": {"status": "printing", "temps": {"tool0": {"actual": 210.0, "target": 210.0}, "bed": {"actual": 60.0, "target": 60.0}}}, "job": {"filename": "model.gcode", "progress": 42.5, "time_left": 3600}}}

kiln print model.gcode --json (started):

{"status": "success", "message": "Print started", "filename": "model.gcode"}

kiln order quote model.stl -m pla_standard --json:

{"status": "success", "quote_id": "q_abc123", "price_usd": 12.50, "lead_time_days": 5, "shipping_options": [{"id": "std", "price_usd": 4.99, "days": 7}]}

MCP Interface

If your platform has an MCP client, Kiln exposes 430 tools as an MCP server. Tools are called by name with JSON arguments — your MCP client handles the transport.

Starting the MCP Server

kiln serve

Or configure in Claude Desktop (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "kiln": {
      "command": "kiln",
      "args": ["serve"],
      "env": {
        "KILN_PRINTER_HOST": "http://your-printer-ip",
        "KILN_PRINTER_API_KEY": "your_key",
        "KILN_PRINTER_TYPE": "octoprint"
      }
    }
  }
}

MCP Tool Call Format

{"name": "printer_status", "arguments": {}}
{"name": "start_print", "arguments": {"filename": "model.gcode"}}
{"name": "set_temperature", "arguments": {"tool_temp": 210, "bed_temp": 60}}
{"name": "send_gcode", "arguments": {"commands": ["G28", "G1 X50 Y50 F3000"]}}
{"name": "upload_file", "arguments": {"file_path": "/path/to/model.gcode"}}

Parameter names and types are auto-documented by the server — your client shows them. Call get_started() for an onboarding guide.

MCP Response Format

All tools return JSON objects. Same pattern as CLI:

• Success: tool-specific fields
• Error: {"error": "message", "status": "error"}
• Warnings: "warnings" array alongside data

Setup

Set these environment variables before using Kiln (CLI or MCP):

export KILN_PRINTER_HOST="http://your-printer-ip"
export KILN_PRINTER_API_KEY="your_api_key"
export KILN_PRINTER_TYPE="octoprint"   # or: moonraker, bambu, prusaconnect, elegoo

Verify connectivity:

kiln status --json

File Intelligence

G-code files on printers often have cryptic names (test5112.gcode, spacer_v3.gcode). Kiln extracts metadata from G-code headers so you can reason about files without relying on filenames.

# Analyze a specific file [safe]
kiln analyze-file benchy.gcode --json

Returns structured metadata:

{
  "material": "PLA",
  "estimated_time_seconds": 6150,
  "tool_temp": 210.0,
  "bed_temp": 60.0,
  "slicer": "PrusaSlicer 2.7.0",
  "layer_height": 0.2,
  "filament_used_mm": 4523.45
}

How to use file intelligence:

1. List files: kiln files --json — each file now includes metadata
2. Check material match before printing: compare material field with loaded material (kiln material show --json)
3. Check estimated time: use estimated_time_seconds to assess duration
4. Validate temperatures: compare tool_temp/bed_temp with safety profile

Example: Choosing an overnight print

"I found 3 files on your printer:
- benchy.gcode — PLA, ~45 min, 210°C/60°C
- phone_stand.gcode — PLA, ~2h 10m, 210°C/60°C
- test5112.gcode — PETG, ~8h 30m, 240°C/80°C

You have PLA loaded. phone_stand.gcode is the best match for overnight
(PLA-compatible, reasonable duration). Want me to start it?"

Safety Model

Kiln enforces physical safety — it will hard-block commands that exceed temperature limits, contain dangerous G-code, or fail pre-flight checks. You cannot bypass these.

You enforce operational judgment — deciding when to ask the human for confirmation vs. acting autonomously. This document defines those rules.

Autonomy Tiers

The human configures how much autonomous control you have. Check kiln autonomy show --json to see the current level.

Level 1 Constraints

At Level 1, the human pre-configures safety boundaries:

# ~/.kiln/config.yaml