@aubron/ankerts-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1109 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { AnkerClient as AnkerClient2, toAnkerError } from "@aubron/ankerts";
+
+// src/globals.ts
+import { parseArgs } from "util";
+var GLOBAL_FLAGS = [
+  {
+    name: "output",
+    type: "string",
+    description: "Output format: json | ndjson | text. Default: json when piped, text on a TTY."
+  },
+  { name: "json", type: "boolean", description: "Alias for --output json." },
+  {
+    name: "quiet",
+    type: "boolean",
+    short: "q",
+    description: "Bare values, one per line \u2014 for $() capture and xargs."
+  },
+  {
+    name: "fields",
+    type: "string",
+    description: "Comma-separated field mask (dotted paths) to trim large objects."
+  },
+  { name: "dry-run", type: "boolean", description: "Validate and report; mutate nothing." },
+  { name: "yes", type: "boolean", description: "Bypass confirmations / safety warnings." },
+  {
+    name: "printer",
+    type: "string",
+    description: "Target printer by DUID, serial, name, or index. Default: selected printer."
+  },
+  { name: "timeout", type: "string", description: "Override the command timeout, in seconds." },
+  { name: "no-input", type: "boolean", description: "Never prompt; fail fast instead." },
+  { name: "insecure", type: "boolean", description: "Disable TLS verification (testing only)." },
+  { name: "help", type: "boolean", short: "h", description: "Show help for this command." }
+];
+var EXIT_CODES = {
+  0: "success",
+  1: "generic / unexpected failure",
+  2: "usage error (bad/missing args)",
+  3: "auth error (login required/expired/captcha)",
+  4: "printer not found / not selected",
+  5: "connectivity/timeout \u2014 RETRIABLE",
+  6: "transport unavailable for this op (e.g. upload needs LAN)",
+  7: "printer-side error (gcode rejected, job refused)"
+};
+function buildParseOptions(flags) {
+  const options = {};
+  for (const f of flags) {
+    options[f.name] = {
+      type: f.type === "boolean" ? "boolean" : "string",
+      ...f.short ? { short: f.short } : {},
+      ...f.multiple ? { multiple: true } : {}
+    };
+  }
+  return options;
+}
+function parseCommandArgs(argv, flags) {
+  const all = [
+    ...GLOBAL_FLAGS,
+    ...flags.filter((f) => !GLOBAL_FLAGS.some((g) => g.name === f.name))
+  ];
+  const numberFlags = new Set(all.filter((f) => f.type === "number").map((f) => f.name));
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: buildParseOptions(all),
+    allowPositionals: true,
+    strict: true
+  });
+  const out = {};
+  for (const [k, v] of Object.entries(values)) {
+    out[k] = numberFlags.has(k) && typeof v === "string" ? Number(v) : v;
+  }
+  return { values: out, positionals };
+}
+function extractGlobals(values) {
+  const fields = typeof values.fields === "string" ? values.fields.split(",").map((s) => s.trim()) : void 0;
+  return {
+    output: typeof values.output === "string" ? values.output : void 0,
+    json: values.json === true,
+    quiet: values.quiet === true,
+    fields,
+    dryRun: values["dry-run"] === true,
+    yes: values.yes === true,
+    printer: typeof values.printer === "string" ? values.printer : void 0,
+    timeout: typeof values.timeout === "string" ? Number(values.timeout) : void 0,
+    noInput: values["no-input"] === true,
+    reveal: values.reveal === true,
+    insecure: values.insecure === true,
+    help: values.help === true
+  };
+}
+
+// src/describe.ts
+function buildDescribeTree(specs) {
+  return {
+    name: "ankerts",
+    summary: "Agent-first CLI for AnkerMake / eufyMake M5 printers.",
+    transports: {
+      mqtt: { use: "gcode, status, control", reachability: "anywhere (internet + creds)" },
+      pppp: { use: "file upload, camera", reachability: "LAN only (needs discovered IP)" },
+      https: { use: "login, account, printer list", reachability: "anywhere" }
+    },
+    exitCodes: Object.fromEntries(Object.entries(EXIT_CODES).map(([k, v]) => [Number(k), v])),
+    globalFlags: GLOBAL_FLAGS,
+    commands: specs.map((s) => ({
+      path: s.path,
+      command: s.path.join(" "),
+      summary: s.summary,
+      description: s.description,
+      transport: s.transport,
+      args: s.args,
+      flags: s.flags,
+      exitCodes: s.exitCodes,
+      examples: s.examples
+    }))
+  };
+}
+
+// src/spec.ts
+function defineCommand(input) {
+  return {
+    description: input.summary,
+    transport: "none",
+    flags: [],
+    args: [],
+    exitCodes: [0, 1, 2],
+    examples: [],
+    ...input
+  };
+}
+
+// src/commands/auth.ts
+import { AnkerClient, ConfigStore, redactConfig, UsageError as UsageError2 } from "@aubron/ankerts";
+
+// src/runtime.ts
+import { UsageError } from "@aubron/ankerts";
+function str(v) {
+  return typeof v === "string" ? v : "";
+}
+function requirePositional(ctx, index, name) {
+  const v = ctx.args.positionals[index];
+  if (!v) {
+    throw new UsageError({
+      message: `missing required argument <${name}>`,
+      hint: `See \`ankerts ${ctx.args.positionals.slice(0, index).join(" ")} --help\`.`,
+      input: { argument: name }
+    });
+  }
+  return v;
+}
+function timeoutMs(ctx, fallbackMs) {
+  const t = ctx.globals.timeout;
+  return typeof t === "number" && !Number.isNaN(t) ? t * 1e3 : fallbackMs;
+}
+function flagBool(args, name) {
+  return args.values[name] === true;
+}
+function flagStr(args, name) {
+  const v = args.values[name];
+  return typeof v === "string" ? v : void 0;
+}
+
+// src/commands/auth.ts
+var login = defineCommand({
+  path: ["login"],
+  summary: "Authenticate to an AnkerMake/eufyMake account and store credentials.",
+  description: "Logs in over the cloud HTTPS API (email/password \u2192 token; the password is ECDH-encrypted in transit), then fetches the account's printer list and keys. If the API returns a captcha challenge, you get a structured, actionable error (captcha_id + image URL) \u2014 never a hang. Re-run with --captcha-answer to solve it.",
+  transport: "https",
+  flags: [
+    { name: "email", type: "string", description: "Account email." },
+    {
+      name: "password",
+      type: "string",
+      description: "Account password. Use `-` to read from stdin, or set ANKER_PASSWORD."
+    },
+    { name: "country", type: "string", description: "2-letter country code selecting the region." },
+    { name: "save", type: "boolean", description: "Persist credentials to the config store." },
+    { name: "captcha-id", type: "string", description: "Captcha id from a prior captcha error." },
+    { name: "captcha-answer", type: "string", description: "Captcha answer text." }
+  ],
+  exitCodes: [0, 2, 3, 5],
+  examples: [
+    {
+      description: "Log in and store credentials",
+      cmd: "ankerts login --email me@example.com --password hunter2 --country US --save",
+      output: '{ "account": { "email": "me@example.com", "region": "us" }, "printers": 1 }'
+    },
+    {
+      description: "Read the password from stdin (keeps it out of argv/history)",
+      cmd: "echo $PW | ankerts login --email me@example.com --password - --country US --save"
+    }
+  ],
+  async run(ctx) {
+    const email = str(ctx.args.values.email);
+    const country = str(ctx.args.values.country);
+    let password = flagStr(ctx.args, "password") ?? process.env.ANKER_PASSWORD ?? "";
+    if (password === "-") password = (await ctx.readStdin()).trim();
+    if (!email || !country) {
+      throw new UsageError2({
+        message: "--email and --country are required",
+        input: { email: email || null, country: country || null }
+      });
+    }
+    if (!password) {
+      throw new UsageError2({
+        message: "no password provided",
+        hint: "Pass --password <pw>, set ANKER_PASSWORD, or use --password - to read stdin."
+      });
+    }
+    if (ctx.globals.dryRun) {
+      ctx.out.emit({ dryRun: true, action: "login", email, country });
+      return;
+    }
+    const client = await AnkerClient.login({
+      email,
+      password,
+      country,
+      captchaId: flagStr(ctx.args, "captcha-id"),
+      captchaAnswer: flagStr(ctx.args, "captcha-answer"),
+      save: flagBool(ctx.args, "save")
+    });
+    const cfg = client.getConfig();
+    if (!flagBool(ctx.args, "save")) {
+      ctx.out.log("note: credentials were NOT saved (pass --save to persist).");
+    } else {
+      ctx.out.log("login ok \u2014 credentials stored.");
+    }
+    ctx.out.emit({ account: redactConfig(cfg).account, printers: cfg.printers.length });
+  }
+});
+var logout = defineCommand({
+  path: ["logout"],
+  summary: "Remove stored credentials and printer config.",
+  description: "Clears the account token from the local config store. Printers are forgotten.",
+  transport: "none",
+  exitCodes: [0, 1],
+  examples: [{ cmd: "ankerts logout" }],
+  run(ctx) {
+    const store = new ConfigStore();
+    if (ctx.globals.dryRun) {
+      ctx.out.emit({ dryRun: true, action: "logout", path: store.path });
+      return;
+    }
+    store.save({ account: null, printers: [] });
+    ctx.out.emit({ ok: true, message: "logged out" });
+  }
+});
+var configShow = defineCommand({
+  path: ["config", "show"],
+  summary: "Show the current stored config (secrets redacted by default).",
+  description: "Prints the account and per-printer records from the local config store. Secrets (auth token, MQTT/PPPP keys) are redacted unless you pass --reveal.",
+  transport: "none",
+  flags: [{ name: "reveal", type: "boolean", description: "Show secret values in clear text." }],
+  exitCodes: [0, 1],
+  examples: [
+    { description: "Inspect config safely", cmd: "ankerts config show" },
+    {
+      description: "Get the first printer's DUID",
+      cmd: "ankerts config show --json | jq -r '.printers[0].duid'"
+    }
+  ],
+  run(ctx) {
+    const store = new ConfigStore();
+    ctx.out.emit(redactConfig(store.load(), flagBool(ctx.args, "reveal")));
+  }
+});
+var authCommands = [login, logout, configShow];
+
+// src/commands/gcode.ts
+import { readFile } from "fs/promises";
+import { inspectGcode } from "@aubron/ankerts";
+function warnIfMutating(ctx, command) {
+  if (ctx.globals.yes || ctx.globals.dryRun) return;
+  const info = inspectGcode(command);
+  if (info.mutatesState && info.note) ctx.out.log(`warning: ${info.note}`);
+}
+var gcode = defineCommand({
+  path: ["gcode"],
+  summary: "Send gcode and return the parsed response (truncation-aware).",
+  description: "Publishes gcode over MQTT and parses the reply into raw text, fields/reports, ok, recognized, and timedOut (distinct from recognized:false \u2014 a timeout is not a rejection). The firmware returns each reply as a single ~512-byte serial-buffer snapshot, so long replies (or one caught mid-write, e.g. M900) come back partial: those are flagged `truncated:true` (with a stderr warning) instead of being passed off as complete like the reference's `echo:Ad` bug. Accepts one command as args, many via --batch <file>, or `-` to read stdin (one per line, NDJSON result per line). State-mutating commands print a volatility warning on stderr unless --yes. Default timeouts are latency-class aware (M109/M190/G29/M303 get minutes); --wait-motion appends M400 so the call returns on true motion completion, not queue-accept.",
+  transport: "mqtt",
+  args: [
+    {
+      name: "CMD",
+      description: "Gcode to send (or `-` to read commands from stdin).",
+      variadic: true
+    }
+  ],
+  flags: [
+    { name: "no-wait", type: "boolean", description: "Fire-and-forget; don't collect a response." },
+    {
+      name: "wait-motion",
+      type: "boolean",
+      description: "Append M400 \u2014 return on motion complete."
+    },
+    { name: "batch", type: "string", description: "Read commands from a file (one per line)." }
+  ],
+  exitCodes: [0, 1, 3, 4, 5, 7],
+  examples: [
+    {
+      description: "Read the firmware name (long reply \u2192 truncated:true, name still present)",
+      cmd: "ankerts gcode M115 --json | jq '{firmware:.fields.FIRMWARE_NAME, truncated}'",
+      output: '{ "firmware": "Marlin V8111_V3.2.2 (...)", "truncated": true }'
+    },
+    {
+      description: "A short reply comes back whole",
+      cmd: "ankerts gcode M105 --json | jq -r '.raw'",
+      output: "ok T:29.12 /0.00 B:30.31 /0.00"
+    },
+    {
+      description: "Detect an unknown command (not a truncation)",
+      cmd: "ankerts gcode M9998 --json | jq '{recognized, truncated}'",
+      output: '{ "recognized": false, "truncated": false }'
+    },
+    {
+      description: "Batch from stdin, one NDJSON result per line",
+      cmd: "printf 'M104 S200\\nM140 S60\\n' | ankerts gcode -"
+    }
+  ],
+  async run(ctx) {
+    const client = ctx.client();
+    const opts = {
+      timeoutMs: timeoutMs(ctx, 0) || void 0,
+      wait: !flagBool(ctx.args, "no-wait"),
+      waitMotion: flagBool(ctx.args, "wait-motion")
+    };
+    const batchFile = flagStr(ctx.args, "batch");
+    let commands;
+    if (batchFile) {
+      commands = (await readFile(batchFile, "utf8")).split("\n").map((l) => l.trim()).filter(Boolean);
+    } else if (ctx.args.positionals[0] === "-") {
+      commands = (await ctx.readStdin()).split("\n").map((l) => l.trim()).filter(Boolean);
+    } else {
+      const single = ctx.args.positionals.join(" ").trim();
+      if (!single) {
+        requirePositional(ctx, 0, "CMD");
+      }
+      commands = [single];
+    }
+    if (ctx.globals.dryRun) {
+      ctx.out.emit(
+        commands.map((command) => ({ dryRun: true, command, inspect: inspectGcode(command) }))
+      );
+      return;
+    }
+    for (const command of commands) warnIfMutating(ctx, command);
+    if (commands.length === 1) {
+      const result = await client.gcode(commands[0], opts);
+      await client.close();
+      if (result.truncated) {
+        ctx.out.log(
+          "warning: reply was truncated by the firmware's ~512-byte serial buffer (truncated=true) \u2014 output may be incomplete."
+        );
+      }
+      ctx.out.emit(result);
+      return;
+    }
+    for await (const result of client.gcodeBatch(commands, opts)) {
+      ctx.out.ndjsonLine(result);
+    }
+    await client.close();
+  }
+});
+var stateSnapshot = defineCommand({
+  path: ["state", "snapshot"],
+  summary: "Capture machine settings (M503) as a parsed object.",
+  description: "Sends M503 over MQTT and parses the settings dump into a structured object (linear advance K, hotend PID, steps/mm, probe Z offset, and the report map). NOTE: M503's output usually exceeds the firmware's ~512-byte reply window, so the snapshot can be partial \u2014 check `result.truncated`. (A piecewise reader that stitches the full set from short per-setting queries is tracked as a follow-up.) Pair with `state restore` to undo volatile changes.",
+  transport: "mqtt",
+  exitCodes: [0, 1, 3, 4, 5],
+  examples: [
+    {
+      description: "Snapshot before tuning",
+      cmd: "ankerts state snapshot --json | jq '.hotendPid'"
+    }
+  ],
+  async run(ctx) {
+    const client = ctx.client();
+    const settings = await client.snapshotState();
+    await client.close();
+    ctx.out.emit(settings);
+  }
+});
+var stateRestore = defineCommand({
+  path: ["state", "restore"],
+  summary: "Reload settings from EEPROM (M501), discarding volatile changes.",
+  description: "Sends M501 to reload the saved EEPROM settings, reverting any volatile (RAM) changes made this power cycle (e.g. an `M900 K` that would otherwise contaminate the next print).",
+  transport: "mqtt",
+  exitCodes: [0, 1, 3, 4, 5, 7],
+  examples: [{ cmd: "ankerts state restore" }],
+  async run(ctx) {
+    const client = ctx.client();
+    const result = await client.restoreState();
+    await client.close();
+    ctx.out.emit(result);
+  }
+});
+var gcodeCommands = [gcode, stateSnapshot, stateRestore];
+
+// src/commands/jobs.ts
+import { AnkerError } from "@aubron/ankerts";
+var discover = defineCommand({
+  path: ["discover"],
+  summary: "Find printers on the local network (PPPP LAN search).",
+  description: "Broadcasts a PPPP LAN_SEARCH over UDP and collects replies. Discovery is flaky (UDP broadcast), so it retries. With --store, the discovered IPs are written into config \u2014 the prerequisite for LAN file upload. `print` runs this automatically when a printer's IP is missing.",
+  transport: "pppp",
+  flags: [
+    { name: "store", type: "boolean", description: "Write discovered IPs into config." },
+    { name: "retries", type: "string", description: "Discovery attempts (default 3)." }
+  ],
+  exitCodes: [0, 1, 5],
+  examples: [
+    { description: "Discover and store IPs", cmd: "ankerts discover --store" },
+    {
+      description: "Bare DUIDs of printers on the LAN",
+      cmd: "ankerts discover -q | xargs -n1 echo found:"
+    }
+  ],
+  async run(ctx) {
+    const client = ctx.client();
+    const retries = Number(ctx.args.values.retries ?? 3) || 3;
+    const found = await client.discoverLan({
+      store: flagBool(ctx.args, "store"),
+      retries,
+      timeoutMs: timeoutMs(ctx, 1e3)
+    });
+    ctx.out.emit(found, { quietProjection: ["duid"] });
+  }
+});
+var print = defineCommand({
+  path: ["print"],
+  summary: "Upload a gcode file over the LAN and start the print.",
+  description: "Uploads via PPPP (LAN only) and, by default, starts the job. Auto-runs discovery to find/store the printer IP if it is unknown. Off-LAN this exits 6 (transport unavailable) with a structured error naming PPPP and the `discover --store` fix. Upload progress streams as NDJSON on stderr. `print` returns a job handle by default (it does NOT hold the process for the whole print) \u2014 use --wait-start to block until the job actually starts, or detach and poll with `printer wait --until complete`. By DEFAULT it auto-fixes the LCD ETA: a third-party slicer's embedded time/filament estimate is transcoded into the Anker `;TIME:` header (auto-detected \u2014 a no-op on natively-sliced files; always on a copy, never mutating your file). Pass --no-fix-metadata to upload the file byte-for-byte untouched.",
+  transport: "pppp",
+  args: [{ name: "file.gcode", description: "Path to the gcode file to upload.", required: true }],
+  flags: [
+    { name: "no-start", type: "boolean", description: "Upload only; don't start the print." },
+    { name: "transport", type: "string", description: "lan | auto (default auto; LAN only here)." },
+    {
+      name: "no-fix-metadata",
+      type: "boolean",
+      description: "Upload the file untouched (skip the automatic slicer-metadata ETA fix)."
+    },
+    {
+      name: "wait-start",
+      type: "boolean",
+      description: "Block until the job state flips to printing."
+    },
+    {
+      name: "wait-complete",
+      type: "boolean",
+      description: "Block until the print completes (long-running, resumable)."
+    }
+  ],
+  exitCodes: [0, 1, 4, 5, 6, 7],
+  examples: [
+    {
+      description: "Upload + start (auto-discovers IP if needed)",
+      cmd: "ankerts print tower.gcode",
+      output: '{ "name": "tower.gcode", "started": true, "transport": "lan" }'
+    },
+    {
+      description: "Off-LAN failure is structured and actionable (exit 6)",
+      cmd: "ankerts print tower.gcode --json | jq -r '.error.hint'",
+      output: "Run `ankerts discover --store` while on the same LAN as the printer, then retry."
+    },
+    {
+      description: "Upload an OrcaSlicer file untouched (no automatic ETA fix)",
+      cmd: "ankerts print tower.gcode --no-fix-metadata"
+    }
+  ],
+  async run(ctx) {
+    const file = requirePositional(ctx, 0, "file.gcode");
+    const client = ctx.client();
+    if (ctx.globals.dryRun) {
+      ctx.out.emit({
+        dryRun: true,
+        action: "print",
+        file,
+        start: !flagBool(ctx.args, "no-start"),
+        fixMetadata: !flagBool(ctx.args, "no-fix-metadata")
+      });
+      return;
+    }
+    const result = await client.uploadAndPrint(file, {
+      start: !flagBool(ctx.args, "no-start"),
+      fixMetadata: flagBool(ctx.args, "fix-metadata"),
+      transport: ctx.args.values.transport ?? "auto",
+      onProgress: (p) => ctx.out.log(JSON.stringify({ event: "upload", ...p }))
+    });
+    if (flagBool(ctx.args, "wait-start") || flagBool(ctx.args, "wait-complete")) {
+      const { parseWaitCondition: parseWaitCondition2 } = await import("@aubron/ankerts");
+      const cond = flagBool(ctx.args, "wait-complete") ? "complete" : "printing";
+      ctx.out.log(`waiting for job to reach "${cond}"\u2026`);
+      await client.waitFor(parseWaitCondition2(cond), {
+        timeoutMs: timeoutMs(ctx, flagBool(ctx.args, "wait-complete") ? 864e5 : 12e4),
+        onTick: (s) => ctx.out.log(JSON.stringify(s))
+      });
+    }
+    await client.close();
+    ctx.out.emit(result);
+  }
+});
+function jobControl(verb) {
+  return defineCommand({
+    path: ["job", verb],
+    summary: `${verb[0].toUpperCase()}${verb.slice(1)} the current print job.`,
+    description: `Sends the ${verb} control command to the printer over MQTT (PRINT_CONTROL). The control values were reverse-engineered and confirmed live on an M5: cancel returns the printer to idle with the heaters off; pause/resume toggle the print.`,
+    transport: "mqtt",
+    exitCodes: [0, 1, 3, 4, 5, 7],
+    examples: [{ cmd: `ankerts job ${verb}` }],
+    async run(ctx) {
+      const client = ctx.client();
+      if (ctx.globals.dryRun) {
+        ctx.out.emit({ dryRun: true, action: `job ${verb}` });
+        return;
+      }
+      if (verb === "cancel") await client.cancelJob();
+      else if (verb === "pause") await client.pauseJob();
+      else await client.resumeJob();
+      await client.close();
+      ctx.out.emit({ ok: true, action: verb });
+    }
+  });
+}
+var camera = defineCommand({
+  path: ["camera", "capture"],
+  summary: "Capture the printer's video stream (PPPP, optional).",
+  description: "Captures the H.264 video stream over PPPP. This is lower-priority and not yet wired in this version; it returns a structured not-implemented error so agents can branch cleanly rather than hang.",
+  transport: "pppp",
+  args: [
+    { name: "out.h264", description: "Output file for the raw H.264 stream.", required: true }
+  ],
+  flags: [{ name: "max-size", type: "string", description: "Maximum bytes to capture." }],
+  exitCodes: [0, 1, 4, 5],
+  examples: [{ cmd: "ankerts camera capture out.h264 --max-size 5000000" }],
+  run(ctx) {
+    requirePositional(ctx, 0, "out.h264");
+    throw new AnkerError({
+      code: "not_implemented",
+      message: "Camera capture is not yet implemented in this version.",
+      transport: "pppp",
+      hint: "Use `ankerts printer status` for telemetry; camera streaming is planned."
+    });
+  }
+});
+var jobCommands = [
+  discover,
+  print,
+  jobControl("cancel"),
+  jobControl("pause"),
+  jobControl("resume"),
+  camera
+];
+
+// src/commands/printer.ts
+import { parseWaitCondition } from "@aubron/ankerts";
+var list = defineCommand({
+  path: ["printer", "list"],
+  summary: "List the printers on the account.",
+  description: "Reads the printer list from stored config (populated at login). No network call. Each entry includes DUID, serial, model, and the discovered LAN IP (empty until you run `ankerts discover --store`).",
+  transport: "none",
+  exitCodes: [0, 1, 4],
+  examples: [
+    {
+      description: "Get the first printer's DUID, clean stdout",
+      cmd: "ankerts printer list --json | jq -r '.[0].duid'",
+      output: "USPRAKM-000994-YYLLG"
+    },
+    { description: "Bare DUIDs for scripting", cmd: "ankerts printer list -q" }
+  ],
+  run(ctx) {
+    const printers = ctx.client().listPrinters();
+    ctx.out.emit(printers, { quietProjection: ["duid"] });
+  }
+});
+var status = defineCommand({
+  path: ["printer", "status"],
+  summary: "Show temperatures, job state, and progress.",
+  description: "Queries server-authoritative status over MQTT and normalizes it: temperatures in \xB0C (converted from 1/100 \xB0C), progress 0\u2013100. For third-party-sliced gcode the firmware's headline ETA is unreliable, so etaReliable is false and the bogus ETA is omitted. With --watch, streams status objects as NDJSON (one per line) until interrupted.",
+  transport: "mqtt",
+  flags: [
+    { name: "watch", type: "boolean", description: "Stream status as NDJSON until interrupted." },
+    { name: "poll", type: "string", description: "Watch poll interval in seconds (default 2)." }
+  ],
+  exitCodes: [0, 1, 3, 4, 5],
+  examples: [
+    { description: "One-shot status", cmd: "ankerts printer status --json | jq '.nozzle'" },
+    {
+      description: "Watch a print (NDJSON stream)",
+      cmd: "ankerts printer status --watch | jq -r '.job.progressPct'"
+    }
+  ],
+  async run(ctx) {
+    const client = ctx.client();
+    if (!flagBool(ctx.args, "watch")) {
+      const s = await client.getStatus();
+      await client.close();
+      ctx.out.emit(s);
+      return;
+    }
+    const pollSec = Number(ctx.args.values.poll ?? 2) || 2;
+    ctx.out.log("watching status (NDJSON on stdout); Ctrl-C to stop.");
+    await client.subscribeEvents(() => {
+    });
+    for (; ; ) {
+      const s = await client.getStatus();
+      ctx.out.ndjsonLine(s);
+      await new Promise((r) => setTimeout(r, pollSec * 1e3));
+    }
+  }
+});
+var select = defineCommand({
+  path: ["printer", "select"],
+  summary: "Set the default printer in config.",
+  description: "Selects a printer (by DUID, serial, name, or index) as the default target for subsequent commands. Persisted to the config store.",
+  transport: "none",
+  args: [
+    {
+      name: "duid|index",
+      description: "Printer reference (DUID, serial, name, or index).",
+      required: true
+    }
+  ],
+  exitCodes: [0, 1, 2, 4],
+  examples: [
+    { description: "Select by index", cmd: "ankerts printer select 0" },
+    { description: "Select by DUID", cmd: "ankerts printer select USPRAKM-000994-YYLLG" }
+  ],
+  run(ctx) {
+    const ref = requirePositional(ctx, 0, "duid|index");
+    const printer = ctx.client().selectPrinter(ref);
+    ctx.out.emit({ selected: printer.duid, name: printer.name });
+  }
+});
+var wait = defineCommand({
+  path: ["printer", "wait"],
+  summary: "Block until a printer condition holds (re-attachable).",
+  description: "Watches server-authoritative state and resolves once the condition holds \u2014 so a wait killed mid-flight can simply be re-issued and re-derives current state. Streams NDJSON status ticks on stderr while waiting; on success prints the final status to stdout (exit 0); on timeout exits 5 (retriable). Conditions: connected | lan | nozzle>=C | bed>=C | temp-stable | printing | idle | progress>=pct | layer>=n | complete | failed | cancelled | runout.",
+  transport: "mqtt",
+  flags: [
+    { name: "until", type: "string", description: "The condition to wait for (required)." },
+    { name: "poll", type: "string", description: "Poll interval in seconds (default 2)." }
+  ],
+  exitCodes: [0, 1, 3, 4, 5],
+  examples: [
+    {
+      description: "Wait for the job to actually start (not just upload-accepted)",
+      cmd: "ankerts printer wait --until printing --timeout 120"
+    },
+    {
+      description: "Cool down after the print completes",
+      cmd: 'ankerts printer wait --until complete && ankerts gcode "M104 S0"'
+    }
+  ],
+  async run(ctx) {
+    const until = ctx.args.values.until;
+    if (typeof until !== "string" || until === "") {
+      const { UsageError: UsageError4 } = await import("@aubron/ankerts");
+      throw new UsageError4({ message: "--until <condition> is required" });
+    }
+    const cond = parseWaitCondition(until);
+    const client = ctx.client();
+    const pollSec = Number(ctx.args.values.poll ?? 2) || 2;
+    const final = await client.waitFor(cond, {
+      timeoutMs: timeoutMs(ctx, 6e5),
+      pollMs: pollSec * 1e3,
+      onTick: (s) => ctx.out.log(JSON.stringify(s))
+    });
+    await client.close();
+    ctx.out.emit(final);
+  }
+});
+var printerCommands = [list, status, select, wait];
+
+// src/commands/skills.ts
+import { cpSync, existsSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { UsageError as UsageError3 } from "@aubron/ankerts";
+var SKILL_NAME = "ankerts";
+function bundledSkillDir() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", SKILL_NAME);
+}
+var install = defineCommand({
+  path: ["skills", "install"],
+  summary: "Install the bundled `ankerts` Agent Skill into a skills directory.",
+  description: "Copies the SKILL.md that ships inside this package into a skills directory so an agent learns how to drive ankerts. Defaults to the project's .claude/skills/; use --global for ~/.claude/skills, or --dir to target any directory (works for any SKILL.md-compatible agent). Explicit and idempotent \u2014 re-run with --force to overwrite.",
+  transport: "none",
+  flags: [
+    {
+      name: "global",
+      type: "boolean",
+      description: "Install into ~/.claude/skills instead of the project."
+    },
+    {
+      name: "dir",
+      type: "string",
+      description: "Target skills directory (overrides --global/project)."
+    },
+    { name: "force", type: "boolean", description: "Overwrite an existing install." }
+  ],
+  exitCodes: [0, 1, 2],
+  examples: [
+    { description: "Install into the current project", cmd: "ankerts skills install" },
+    { description: "Install for all projects", cmd: "ankerts skills install --global" },
+    {
+      description: "Install for another agent",
+      cmd: "ankerts skills install --dir ~/.codex/skills"
+    }
+  ],
+  run(ctx) {
+    const src = bundledSkillDir();
+    if (!existsSync(src)) {
+      throw new UsageError3({
+        code: "skill_not_bundled",
+        message: "Bundled skill not found next to the CLI",
+        hint: "Reinstall @aubron/ankerts-cli \u2014 the published package ships skills/ankerts/SKILL.md."
+      });
+    }
+    const dir = flagStr(ctx.args, "dir");
+    const skillsDir = dir ? resolve(dir) : flagBool(ctx.args, "global") ? join(homedir(), ".claude", "skills") : resolve(".claude", "skills");
+    const dest = join(skillsDir, SKILL_NAME);
+    if (existsSync(dest) && !flagBool(ctx.args, "force")) {
+      throw new UsageError3({
+        code: "skill_exists",
+        message: `Skill already installed at ${dest}`,
+        hint: "Re-run with --force to overwrite.",
+        input: { dest }
+      });
+    }
+    if (ctx.globals.dryRun) {
+      ctx.out.emit({ dryRun: true, action: "skills install", from: src, to: dest });
+      return;
+    }
+    cpSync(src, dest, { recursive: true });
+    ctx.out.log(`installed ${SKILL_NAME} skill \u2192 ${dest}`);
+    ctx.out.emit({ installed: dest, skill: SKILL_NAME });
+  }
+});
+var skillsCommands = [install];
+
+// src/commands/index.ts
+var baseCommands = [
+  ...authCommands,
+  ...printerCommands,
+  ...gcodeCommands,
+  ...jobCommands,
+  ...skillsCommands
+];
+var describe = defineCommand({
+  path: ["describe"],
+  summary: "Print the full command tree as JSON (machine-readable introspection).",
+  description: "Emits every command, flag, type, default, exit code, and example as one JSON document \u2014 so an agent can map the tool's entire surface in a single call instead of crawling --help pages.",
+  transport: "none",
+  exitCodes: [0, 1],
+  examples: [
+    {
+      description: "List every command path",
+      cmd: "ankerts describe --json | jq -r '.commands[].command'"
+    }
+  ],
+  run(ctx) {
+    ctx.out.emit(buildDescribeTree(allCommands));
+  }
+});
+var allCommands = [...baseCommands, describe];
+
+// src/help.ts
+var BIN = "ankerts";
+var TRANSPORT_BLURB = {
+  mqtt: "MQTT over TLS (Anker cloud broker) \u2014 works anywhere with internet + credentials.",
+  pppp: "PPPP (P2P over UDP) \u2014 LAN only. Needs the printer's IP stored via discovery.",
+  https: "HTTPS (Anker cloud API) \u2014 account auth and printer list; works anywhere.",
+  none: "No printer transport (local/config operation)."
+};
+function flagUsage(f) {
+  const dashName = f.name;
+  const short = f.short ? `-${f.short}, ` : "";
+  const valued = f.type === "boolean" ? "" : ` <${f.type}>`;
+  const def = f.default !== void 0 ? ` (default: ${String(f.default)})` : "";
+  return `  ${short}--${dashName}${valued}
+      ${f.description}${def}`;
+}
+function renderCommandHelp(spec) {
+  const path = spec.path.join(" ");
+  const argUsage = spec.args.map(
+    (a) => a.required ? `<${a.name}${a.variadic ? "..." : ""}>` : `[${a.name}${a.variadic ? "..." : ""}]`
+  ).join(" ");
+  const lines = [];
+  lines.push(`${BIN} ${path} \u2014 ${spec.summary}`, "");
+  lines.push("USAGE", `  ${BIN} ${path}${argUsage ? ` ${argUsage}` : ""} [flags]`, "");
+  lines.push("DESCRIPTION", `  ${spec.description}`, "");
+  lines.push("TRANSPORT", `  ${TRANSPORT_BLURB[spec.transport]}`, "");
+  if (spec.args.length) {
+    lines.push("ARGUMENTS");
+    for (const a of spec.args) {
+      lines.push(`  ${a.name}${a.variadic ? "..." : ""}    ${a.description}`);
+    }
+    lines.push("");
+  }
+  const cmdFlags = spec.flags.filter((f) => !GLOBAL_FLAGS.some((g) => g.name === f.name));
+  if (cmdFlags.length) {
+    lines.push("FLAGS");
+    for (const f of cmdFlags) lines.push(flagUsage(f));
+    lines.push("");
+  }
+  lines.push("GLOBAL FLAGS");
+  for (const f of GLOBAL_FLAGS) lines.push(flagUsage(f));
+  lines.push("");
+  lines.push("EXIT CODES");
+  for (const code of spec.exitCodes) lines.push(`  ${code}  ${EXIT_CODES[code] ?? ""}`);
+  lines.push("");
+  if (spec.examples.length) {
+    lines.push("EXAMPLES");
+    for (const ex of spec.examples) {
+      if (ex.description) lines.push(`  # ${ex.description}`);
+      lines.push(`  $ ${ex.cmd}`);
+      if (ex.output) for (const o of ex.output.split("\n")) lines.push(`  ${o}`);
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+function renderRootHelp(specs) {
+  const lines = [];
+  lines.push(
+    `${BIN} \u2014 agent-first CLI for AnkerMake / eufyMake M5 printers`,
+    "",
+    "USAGE",
+    `  ${BIN} <noun> <verb> [args] [flags]`,
+    ""
+  );
+  const groups = /* @__PURE__ */ new Map();
+  for (const s of specs) {
+    const noun = s.path[0];
+    (groups.get(noun) ?? groups.set(noun, []).get(noun)).push(s);
+  }
+  lines.push("COMMANDS");
+  for (const [noun, group] of groups) {
+    lines.push(`  ${noun}`);
+    for (const s of group) {
+      lines.push(`    ${s.path.join(" ").padEnd(22)} ${s.summary}`);
+    }
+  }
+  lines.push("");
+  lines.push(
+    "CONCEPTS",
+    "  The M5 speaks THREE independent transports, split by reachability:",
+    "    \u2022 MQTT over TLS  \u2014 gcode, status, control. Works ANYWHERE (internet + creds).",
+    "    \u2022 PPPP over UDP  \u2014 file upload, camera. LAN ONLY; needs a discovered IP.",
+    "    \u2022 HTTPS cloud    \u2014 login, account, printer list. Works anywhere.",
+    "  Cloud-reachable \u2260 LAN-reachable: gcode can work while upload (exit 6) cannot,",
+    "  until you run `ankerts discover --store` on the same LAN as the printer.",
+    "",
+    "OUTPUT",
+    "  Data \u2192 stdout; logs/progress \u2192 stderr. JSON by default when piped (text on a",
+    "  TTY). Use --output, --quiet, and --fields to shape it. `ankerts describe --json`",
+    "  dumps the entire command tree for one-call introspection.",
+    "",
+    `Run \`${BIN} <command> --help\` for details, transport, exit codes, and examples.`
+  );
+  return lines.join("\n");
+}
+
+// src/output.ts
+function resolveMode(opts) {
+  const pick = (v) => v === "json" || v === "ndjson" || v === "text" ? v : void 0;
+  if (opts.json) return "json";
+  return pick(opts.flag) ?? pick(opts.env) ?? (opts.isTty ? "text" : "json");
+}
+function pickFields(value, paths) {
+  if (paths.length === 0) return value;
+  if (Array.isArray(value)) return value.map((v) => pickFields(v, paths));
+  if (value === null || typeof value !== "object") return value;
+  const out = {};
+  for (const path of paths) {
+    const segs = path.split(".");
+    let src = value;
+    for (const s of segs) {
+      src = src && typeof src === "object" ? src[s] : void 0;
+    }
+    if (src !== void 0) out[path] = src;
+  }
+  return out;
+}
+function getPath(obj, path) {
+  let cur = obj;
+  for (const s of path.split(".")) {
+    cur = cur && typeof cur === "object" ? cur[s] : void 0;
+  }
+  return cur;
+}
+function scalar(v) {
+  if (v === null || v === void 0) return "";
+  if (typeof v === "object") return JSON.stringify(v);
+  return String(v);
+}
+var Output = class {
+  mode;
+  quiet;
+  fields;
+  out;
+  err;
+  color;
+  constructor(opts = {}) {
+    this.mode = opts.mode ?? "json";
+    this.quiet = opts.quiet ?? false;
+    this.fields = opts.fields;
+    this.out = opts.stdout ?? ((s) => process.stdout.write(s));
+    this.err = opts.stderr ?? ((s) => process.stderr.write(s));
+    this.color = !!opts.isTty && !opts.noColor && this.mode === "text";
+  }
+  /** A diagnostic/progress line → stderr (never pollutes stdout). */
+  log(message) {
+    this.err(`${message}
+`);
+  }
+  /** A single NDJSON object → stdout, newline-terminated (for streams). */
+  ndjsonLine(obj) {
+    const masked = this.fields ? pickFields(obj, this.fields) : obj;
+    this.out(`${JSON.stringify(masked)}
+`);
+  }
+  /**
+   * Emit a command's primary result to stdout, honoring mode/quiet/fields.
+   * `quietProjection` is the default field(s) printed in --quiet mode (e.g.
+   * `["duid"]` so `printer list -q` yields bare DUIDs).
+   */
+  emit(value, opts = {}) {
+    if (this.quiet) return this.emitQuiet(value, opts.quietProjection);
+    const masked = this.fields ? pickFields(value, this.fields) : value;
+    if (this.mode === "ndjson") {
+      const arr = Array.isArray(masked) ? masked : [masked];
+      for (const item of arr) this.out(`${JSON.stringify(item)}
+`);
+      return;
+    }
+    if (this.mode === "json") {
+      this.out(`${JSON.stringify(masked, null, 2)}
+`);
+      return;
+    }
+    this.out(`${this.renderText(masked)}
+`);
+  }
+  emitQuiet(value, projection) {
+    const fields = this.fields ?? projection;
+    const rows = Array.isArray(value) ? value : [value];
+    for (const row of rows) {
+      if (fields && fields.length && row && typeof row === "object") {
+        this.out(`${fields.map((f) => scalar(getPath(row, f))).join("	")}
+`);
+      } else {
+        this.out(`${scalar(row)}
+`);
+      }
+    }
+  }
+  /**
+   * Emit a structured error (brief §3). In json/ndjson mode the `{ error: … }`
+   * body goes to STDOUT so `… --json | jq '.error.hint'` works; in text mode a
+   * readable rendering goes to STDERR. The exit code is set by the caller.
+   */
+  emitError(body) {
+    if (this.mode === "json") {
+      this.out(`${JSON.stringify(body, null, 2)}
+`);
+      return;
+    }
+    if (this.mode === "ndjson") {
+      this.out(`${JSON.stringify(body)}
+`);
+      return;
+    }
+    const e = body.error;
+    const parts = [`error[${e.code}]: ${e.message}`];
+    if (e.transport) parts.push(`  transport: ${String(e.transport)}`);
+    parts.push(`  retriable: ${String(e.retriable)}`);
+    if (e.hint) parts.push(`  hint: ${String(e.hint)}`);
+    if (e.input) parts.push(`  input: ${JSON.stringify(e.input)}`);
+    this.err(`${parts.join("\n")}
+`);
+  }
+  /** Best-effort human rendering for text mode. */
+  renderText(value) {
+    if (value === null || value === void 0) return "";
+    if (Array.isArray(value)) {
+      return value.map((v) => this.renderText(v)).join("\n");
+    }
+    if (typeof value === "object") {
+      return Object.entries(value).map(([k, v]) => `${k}: ${typeof v === "object" && v ? JSON.stringify(v) : scalar(v)}`).join("\n");
+    }
+    return scalar(value);
+  }
+};
+
+// src/index.ts
+function matchCommand(argv) {
+  const nounTokens = [];
+  for (const tok of argv) {
+    if (tok.startsWith("-")) break;
+    nounTokens.push(tok);
+  }
+  let best;
+  for (const spec of allCommands) {
+    if (spec.path.length > nounTokens.length) continue;
+    if (spec.path.every((seg, i) => nounTokens[i] === seg)) {
+      if (!best || spec.path.length > best.path.length) best = spec;
+    }
+  }
+  if (!best) return { rest: argv };
+  const rest = [];
+  let dropped = 0;
+  for (const tok of argv) {
+    if (dropped < best.path.length && !tok.startsWith("-") && tok === best.path[dropped]) {
+      dropped++;
+      continue;
+    }
+    rest.push(tok);
+  }
+  return { spec: best, rest };
+}
+function readStdin() {
+  return new Promise((resolve2, reject) => {
+    if (process.stdin.isTTY) return resolve2("");
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => data += chunk);
+    process.stdin.on("end", () => resolve2(data));
+    process.stdin.on("error", reject);
+  });
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  const isTty = !!process.stdout.isTTY;
+  const noColor = process.env.NO_COLOR !== void 0;
+  const { spec, rest } = matchCommand(argv);
+  let parsed;
+  try {
+    parsed = parseCommandArgs(rest, spec?.flags ?? []);
+  } catch (err) {
+    const out2 = new Output({ mode: isTty ? "text" : "json", isTty, noColor });
+    const e = toAnkerError(err);
+    out2.emitError({ error: { ...e.body(), code: "usage", retriable: false } });
+    return 2;
+  }
+  const globals = extractGlobals(parsed.values);
+  const out = new Output({
+    mode: resolveMode({
+      flag: globals.output,
+      json: globals.json,
+      env: process.env.ANKER_OUTPUT,
+      isTty
+    }),
+    quiet: globals.quiet,
+    fields: globals.fields,
+    isTty,
+    noColor
+  });
+  if (!spec) {
+    if (argv.length && !globals.help && argv[0] !== "help") {
+      out.emitError({
+        error: {
+          code: "unknown_command",
+          message: `unknown command: ${argv.filter((a) => !a.startsWith("-")).join(" ") || "(none)"}`,
+          retriable: false,
+          hint: "Run `ankerts --help`, or `ankerts describe --json` to introspect the full tree."
+        }
+      });
+      return 2;
+    }
+    process.stdout.write(`${renderRootHelp(allCommands)}
+`);
+    return 0;
+  }
+  if (globals.help) {
+    process.stdout.write(`${renderCommandHelp(spec)}
+`);
+    return 0;
+  }
+  const ctx = {
+    out,
+    args: parsed,
+    globals,
+    client: () => AnkerClient2.fromStoredConfig(void 0, {
+      log: (m) => out.log(m),
+      printer: globals.printer,
+      insecure: globals.insecure
+    }),
+    readStdin
+  };
+  try {
+    await spec.run(ctx);
+    return 0;
+  } catch (err) {
+    const e = toAnkerError(err);
+    out.emitError(e.toJSON());
+    return e.exitCode;
+  }
+}
+main().then((code) => process.exit(code)).catch((err) => {
+  process.stderr.write(`${String(err)}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map