octoprint-cli

Agent-friendly command-line interface for OctoPrint 3D printer management.

Designed for autonomous AI agent interaction with structured JSON outputs, clear exit codes, and safety guards for unattended operation.

Installation

pip install .

Or in development mode:

pip install -e ".[dev]"

Quick Start

1. Initialize configuration

octoprint-cli init
# Prompts for host URL and API key, saves to ~/.octoprint-cli/config.yaml

2. Or use environment variables

export OCTOPRINT_HOST="http://octopi.local"
export OCTOPRINT_API_KEY="your_api_key_here"

3. Check printer status

octoprint-cli status --json

Commands

Agent-Friendly Design

Structured JSON Output

Every command supports --json for machine-parseable output:

octoprint-cli status --json

{
  "status": "success",
  "data": {
    "state": "Operational",
    "temperature": {
      "tool0": {"actual": 22.5, "target": 0.0},
      "bed": {"actual": 21.8, "target": 0.0}
    },
    "job": {
      "file": null,
      "completion": null,
      "print_time_left": null
    }
  }
}

Exit Codes

Safety Flags

Destructive operations require explicit confirmation:

# Will fail without --confirm
octoprint-cli print model.gcode --confirm --json

# Cancel with confirmation
octoprint-cli cancel --confirm --json

Idempotent Operations

# Exits 0 if already printing instead of erroring
octoprint-cli print model.gcode --confirm --skip-if-printing --json

Configuration

Configuration is resolved with this precedence (highest first):

1. CLI flags (--host, --api-key)
2. Environment variables (OCTOPRINT_HOST, OCTOPRINT_API_KEY)
3. Config file (~/.octoprint-cli/config.yaml)

Config File Format

host: "http://octopi.local"
api_key: "YOUR_API_KEY_HERE"
timeout: 30
retries: 3

Agent Workflow Example

A typical autonomous print workflow:

# Step 1: Verify printer is ready
octoprint-cli preflight ./model.gcode --json
# Parse JSON, check "ready": true

# Step 2: Upload and print
octoprint-cli print ./model.gcode --confirm --json
# Parse JSON, check "status": "success"

# Step 3: Monitor progress (poll periodically)
octoprint-cli status --json
# Parse JSON, read data.job.completion and data.job.print_time_left

# Step 4: Handle completion or errors based on exit codes
# Exit 0 = success, 1 = offline, 2 = file error, 3 = busy, 4 = other

Error Handling Example

octoprint-cli status --json
echo "Exit code: $?"

{
  "status": "error",
  "data": null,
  "error": {
    "code": "CONNECTION_ERROR",
    "message": "Could not connect to OctoPrint at http://octopi.local"
  }
}

Exit code: 1 (printer offline)

Pre-flight Checks

The preflight command (and automatic checks before print) validates:

• Printer is connected and operational
• Printer is not already printing
• No printer errors detected
• Temperatures are within safe limits
• File exists, has valid extension, reasonable size

octoprint-cli preflight ./model.gcode --json

Temperature Control

# View current temperatures
octoprint-cli temp --json

# Set hotend to 200C and bed to 60C
octoprint-cli temp --tool 200 --bed 60 --json

# Turn off all heaters
octoprint-cli temp --off --json

Raw G-code

# Home all axes
octoprint-cli gcode G28 --json

# Multiple commands
octoprint-cli gcode G28 "M104 S200" "M140 S60" --json

Requirements

• Python 3.8+
• OctoPrint server with API access enabled
• Dependencies: click, requests, pyyaml, rich

License

MIT