CLI commands

Record the final outcome once per named command. Use a stable name such as deploy or projects list, never raw arguments, paths, or customer identifiers.

import { createProblems } from "@problemsdev/sdk";
const problems = createProblems({ publicKey: "YOUR_PUBLIC_KEY" });

try {
  await runDeploy();
  problems.recordCommand("deploy", { exitCode: 0 });
} catch (error) {
  problems.recordCommand("deploy", { exitCode: 1, error });
  process.exitCode = 1;
} finally {
  const { pending, dropped } = await problems.flush();
  // Optional: inspect these counts while debugging delivery.
}

Zero means success; any other integer exit code means error. No stdout, stderr, raw argv, or environment variables are collected. The SDK does not print to your CLI’s output or change its exit code.

Use process.exitCode and let Node exit after the flush. process.exit() and abrupt process termination can lose buffered events. flush() waits at most one second by default; use flush({ timeoutMs: 3000 }) if your CLI can allow longer.

Optional agent status context

With SDK 0.0.2 or later and the project’s public status page enabled in Problems settings, a failed command can check for a matching published problem. Record the original error once, then optionally print the public context to stderr:

try {
  await runDeploy();
  problems.recordCommand("deploy", { exitCode: 0 });
} catch (error) {
  problems.recordCommand("deploy", { exitCode: 1, error });
  process.exitCode = 1;
  console.error(error); // Keep your CLI's existing error formatting here.

  const status = await problems.checkStatus({
    surface: "cli",
    operation: "deploy",
    error,
  });
  if (status.status === "matched") {
    const { reports, url } = status.problem;
    console.error(
      `This error has been reported ${reports} times in the last 5 minutes. ${url}`,
    );
  }
} finally {
  await problems.flush();
}

Use this in place of the basic try/catch above. Keep your command’s usual exit code and structured stdout unchanged. checkStatus returns matched, no_match, or unavailable without recording another event or throwing on lookup failure. It only reads already published problems; it does not wait for this report to be processed. No match is not a claim that the service is healthy.

Network reads time out after 500 ms with no retries. Results are cached for at most 15 seconds, bounded by a matched problem’s expiry. Reporting opt-outs and the same beforeSend filtering apply; see Privacy and delivery.