Start a print

Use this when the user wants to kick off a print right now, not just queue it. Handles:

• Local file: print.stl on Voron-3
• Existing API file id (hex hash)
• Existing queue item id
• Existing user-file UID (from the library)

Steps:

1. Parse the request. Identify:

• Source — exactly one of:
• Local path (contains / or \, starts with ./, ~, or a drive letter).
• API file hex hash (64-hex from a prior upload).
• Queue item id (numeric).
• User-file UID (32-hex from the library) or name (resolve with list_files).
• Target printer(s) by name or id. Resolve names via list_printers.
• Optional custom fields (with <k>=<v>, ...). Resolve names with list_custom_fields_for (category print, subcategory print_job, lowercase). Build the backend array: [{"customFieldId":"<uuid>","value":{"string":"PETG"}}].

1. Refuse up-front on printers that are offline, paused, or reporting an error. Show the error and ask what to do.

1. Run the helper with exactly one source flag:

• Local path: --file <path>
• Existing API file: --file-id <hex>
• Existing queue item: --queue-item-id <n>
• Existing user-file UID: --filesystem <uid>

Bash / Git Bash example:

   ${CLAUDE_PLUGIN_ROOT}/scripts/print.sh \
       --file /path/to/widget.stl \
       --printer-id 7,12 \
       --custom-fields '[{"customFieldId":"project","value":{"string":"acme"}}]'

PowerShell 7+ example:

   ${CLAUDE_PLUGIN_ROOT}/scripts/print.ps1 `
       -File C:\parts\widget.stl `
       -PrinterId "7,12" `
       -CustomFields '[{"customFieldId":"project","value":{"string":"acme"}}]'

1. Flow (for --file): helper uploads to files.simplyprint.io, captures the hex hash, then calls printers/actions/CreateJob with file_id: <hash> and your custom_fields. For other sources, the helper skips the upload and uses file_id / queue_file / filesystem directly.

1. Parse stdout lines JOB_ID=<n> (one per printer). For each, call get_print_job to confirm the job started, and report printer name + job id + panel URL.

If the helper exits non-zero, show the stderr verbatim. Do not retry automatically; the user probably needs to fix something (env vars, printer state, bad custom field id).

If the user only asked to queue (not start now), defer to queue-print instead.