bambu-cli — CLI for Bambu Lab Printers

Fully local 3D printing pipeline for Bambu Lab printers. Runs on Linux, macOS, and Windows. Download models from Printables, slice with OrcaSlicer, and print — all controlled via CLI by any AI agent or by hand. No cloud account needed.

Supports: P1P, P1S, X1C, X1E, A1, A1 Mini (any Bambu printer with LAN mode)

Disclaimer: bambu-cli is an unofficial, community-developed tool. It is not affiliated with, endorsed by, or supported by Bambu Lab. "Bambu Lab" and product names are trademarks of their respective owners, used here only to describe compatibility. The printer protocols (MQTT/FTPS) are reverse-engineered; a firmware update may break functionality without warning — run bambu-cli doctor after printer updates.

Status: Beta (0.1.0). Pre-1.0 — APIs and config keys follow the stability policy in docs/api.md.

Installation

The examples below use the installed bambu-cli command.

pip install bambu-local-cli

Note: the package is published on PyPI as bambu-local-cli (the bambu-cli name there belongs to an unrelated project). The installed command is still bambu-cli.

Or from source:

pip install .
# or: uv sync

Try it without a printer

Before touching a real printer (or configuring one), sanity-check the install with simulation mode:

bambu-cli --sim status

🖨️  Bambu Printer Status
   State: IDLE
   Bed: 25°C / 0°C
   Nozzle: 25°C / 0°C
   Fan: 0 | WiFi: -42dBm
   AMS:
     Unit 0 (humidity 5, 26.0°C)
       ▶ Slot 0: PLA #F2F2F2 | 90%
         Slot 1: PETG #0A0AC8 | 60%
         Slot 2: empty
         Slot 3: TPU #000000 | 45%

Agents should add --json for machine-readable output: bambu-cli --sim status --json.

Features

• Jobs & URL support — Use job when an agent or user gives either a website URL or a local file path. It handles everything in one shot.
• Safe extraction — ZIP archives containing model files are fully supported. Existing files are kept safe by creating a numbered sibling such as model-1.stl. URL downloads and ZIP extraction have a 2048 MB safety limit, adjustable via --max-download-mb.
• Modularity — Run steps individually using download, slice, upload, or print.
• Safety first — One-shot and print flows will not start a physical print unless --confirm is present. Stop, delete, and raw gcode also require --confirm.
• TLS pinning — Pin the printer’s self-signed cert with cert_fingerprint (setup/doctor can capture it). Prefer this over insecure_tls.
• SSRF-hardened downloads — Private/loopback targets are refused unless you pass --allow-private-ips for that invocation.
• Diagnostics — Network, FTPS, and MQTT health checking with doctor and preflight.
• Agent JSON — Structured --json output with published schemas under docs/schemas/.

Setup

Before running setup, gather your printer's LAN IP address, serial number, and LAN-only access code (all shown on the printer's touchscreen under network/LAN settings), and make sure LAN mode is enabled on the printer.

Use the interactive setup command to create your config securely:

bambu-cli setup

Inspect or check the resulting config at any time:

bambu-cli config show       # print config path + contents (access code redacted)
bambu-cli config validate   # check config values without contacting the printer
bambu-cli doctor            # connectivity + live cert fingerprint

OrcaSlicer

Slicing shells out to OrcaSlicer, so bambu-cli needs to know where its binary and bundled profiles/BBL directory live. Setup auto-detects the usual install locations per platform — the macOS app bundle, the Windows Program Files install, and on Linux a $PATH binary (orca-slicer), a Flatpak export, or an AppImage under ~/Applications or ~/tools. If detection misses your install, set orca_slicer and profiles_dir in config.json; when a configured path is wrong, config validate (and slicing) will point you at a working OrcaSlicer it found instead of failing with a generic error.

Usage

# Read-only: check connectivity and printer state (safe, no printer state changes)
bambu-cli status
bambu-cli doctor

For programmatic checks, bambu-cli --json --version emits JSON version details.

# Full workflow (download, slice, upload, and START A PHYSICAL PRINT)
# --confirm is required for any command that begins printing.
bambu-cli job "https://www.printables.com/model/12345-thing" --confirm --json

Monitoring a print

bambu-cli status --monitor (alias --wait) follows a print until it reaches a terminal state (FINISH, FAILED, STOP, or IDLE). For a human it renders a live progress bar; for an agent, add --json to stream newline-delimited JSON (NDJSON) — one compact object per change as the print advances:

bambu-cli status --monitor --json

{"event":"update","command":"status","gcode_state":"RUNNING","mc_percent":42,"layer_num":50,"total_layer_num":200,"mc_remaining_time":33,"nozzle_temper":220,"nozzle_target_temper":220,"bed_temper":60,"bed_target_temper":60,"gcode_file":"model.gcode"}
{"event":"terminal","command":"status","gcode_state":"FINISH","mc_percent":100,"layer_num":200,"total_layer_num":200,"mc_remaining_time":0,"nozzle_temper":38,"nozzle_target_temper":0,"bed_temper":31,"bed_target_temper":0,"gcode_file":"model.gcode"}

Each line is a self-contained JSON object, so an agent can consume the stream incrementally and stop once it sees "event":"terminal". Pair with --sim to exercise the exact event shape without a printer. Schema: docs/schemas/status_event.json.

Global flags

Slicing & AMS

slice accepts common mesh formats in the precedence order STL > STEP > OBJ > 3MF > G-code. When mapping filaments to AMS slots, mapping arguments take zero-or-positive slot indexes.

To decide that mapping, read what is actually loaded first: bambu-cli status shows each AMS unit's trays (filament type, colour, and remaining %), and status --json includes a normalized ams block agents can consume directly:

"ams": {
  "active_tray": 1,
  "units": [
    {"id": 0, "humidity": 4, "temp": 28.5, "trays": [
      {"slot": 0, "type": "PLA",  "color": "F2F2F2", "remain": 80, "empty": false, "active": false},
      {"slot": 1, "type": "PETG", "color": "0A0AC8", "remain": 55, "empty": false, "active": true},
      {"slot": 2, "type": null,   "color": null,     "remain": null, "empty": true,  "active": false}
    ]}
  ]
}

ams is null on printers without an AMS. active marks the currently loaded tray (absolute index unit * 4 + slot); feed the slot indexes to --ams-mapping when printing with --use-ams.

Config reference

Config file location is platform-standard under the user config directory (e.g. ~/.config/bambu/config.json on Linux). Create/edit via bambu-cli setup or manually.

* Either access_code_file or access_code is required. Inline access_code is deprecated and will be removed in a future release.

allow_private_ips is not a config key — use the CLI flag --allow-private-ips per invocation.

Project layout

• bambu_cli/ — Runtime package used by the installed command (bambu-cli).
• scripts/bambu.py — Compatibility wrapper for direct script usage without installing.
• tests/ — Unit, contract, security-marker, and smoke tests.
• docs/ — API, schemas, quality roadmap, test backlog, mutation baseline, live smoke.

Documentation

Ships with the PyPI sdist (and on GitHub)

Wheels contain runtime code only (no docs).

GitHub / contributor only (not in PyPI packages)

License

MIT — Use freely, modify as needed.