Collect. Review. Share.

Installation

Use Node.js 20 or newer. These instructions target source version 0.3.0. Source version and npm publication are separate: check the npm package before using a newly tagged version.

npx crashpack@0.3.0 --no-clipboard --out crash-report.md

For repeated use, install the pinned release:

npm install -g crashpack@0.3.0
crashpack --version
crashpack --no-clipboard --out crash-report.md

Installation and npx may download packages. Installed collection runs offline by default, subject to the network boundaries. Reports are copied to the clipboard by default and saved locally. Start with --no-clipboard so you can review the saved file first.

Run from source

git clone https://github.com/poorvith-mp/crashpack.git
cd crashpack
npm ci
npm run build
node dist/cli.js --version
node dist/cli.js --help

The build embeds the package version. Unbundled development execution can show 0.0.0-dev. Read the checked-out package and release history when comparing a source build with npm.

Workflows

Collect current context

crashpack --no-clipboard --out crash-report.md

Run in the project directory. All eight collectors are selected by default. Missing tools or unavailable context appear as unavailable sections. Default collection doesn't recover logs from an earlier terminal session.

Capture a failing command

crashpack --wrap "npm test" --no-clipboard --lines 200

The command runs in a shell. Its combined output streams live and unredacted to stderr. Crashpack keeps a bounded recent log buffer and waits for the child to exit. Exit zero produces no report; a nonzero exit triggers collection and is returned after output. A long-running server can keep it waiting indefinitely. This isn't a daemon monitor, restart manager, memory dumper, or signal-management interface.

Use piped logs

npm test 2>&1 | crashpack --stdin --no-clipboard
crashpack --stdin --stdout < failure.log

Stdin collection proceeds when the pipe closes, or after 10 seconds with what arrived. With a terminal instead of a pipe, it doesn't wait for typed logs. The log section retains the last requested lines, strips ANSI/control characters, and truncates individual lines beyond 2,000 characters. Shell redirection syntax can vary; use your shell's file-piping equivalent where needed. Stdin mode doesn't preserve the upstream command's exit status.

Write machine-readable output

crashpack --stdout > crash-report.md
crashpack --json > crash-report.json

JSON contains the CrashPack object with redacted section content and reasons; it isn't a raw-secret export. Both modes bypass clipboard copying and ignore --out. If both are supplied, JSON wins. --create additionally attempts a local Markdown save even in these modes, but never uploads. Diagnostics and issue URLs go to stderr.

Prepare an issue URL

crashpack --issue --no-clipboard --out crash-report.md

This constructs a prefilled GitHub or GitLab URL locally. It doesn't open the browser or upload; opening that link sends its encoded title and report to the destination. A recognized origin and the git collector are needed. The URL body falls back to manual-paste guidance when the encoded report exceeds 6,000 characters. Review and paste the full saved report rather than assuming the URL contains it.

Review and create a GitHub issue

crashpack --issue --create --no-clipboard --out crash-report.md

This mode needs a GitHub origin, installed and authenticated GitHub CLI (gh), and interactive stdin and stderr. Crashpack saves the full report locally and prints it for review. It checks gh and authentication, asks for a nonempty single-line title, then asks you to type yes before uploading to the displayed repository on github.com. Review both the report and title for sensitive information.

No upload or prompt occurs with --stdin, --stdout, --json, or a non-TTY run. Declining, missing authentication/tools, an unsupported remote, or upload failure leaves the saved report for manual recovery. GitLab supports URL mode only. A report above 65,536 UTF-16 code units stays intact locally and isn't uploaded or truncated; supplementary Unicode characters count as two units. Review a reduced report or prepare an appropriate manual issue.

On an ambiguous upload failure, check existing repository issues before retrying. A timed-out request may already have created an issue. If the initial local save fails, creation is skipped; preserve the local output before proceeding manually.

CLI flags

Configuration

The CLI looks only in its current working directory, in this order:

1. .crashpackrc (JSON or TOML autodetection)
2. .crashpackrc.json
3. .crashpackrc.toml
4. crashpack.config.json (legacy)
5. The crashpack field in package.json

The first existing file wins. Files aren't merged and parent directories aren't searched. Package metadata without a crashpack field means no configuration. Invalid JSON in that package file still fails loading. Explicit CLI fields override their configured counterparts; unspecified fields retain configuration defaults.

JSON

{
  "only": ["logs", "git", "system", "env"],
  "skip": ["env"],
  "lines": 200,
  "clipboard": false,
  "out": "crash-report.md",
  "redactExtra": ["INTERNAL_[A-Z0-9]+"]
}

TOML

only = ["logs", "git", "system", "env"]
skip = ["env"]
lines = 200
clipboard = false
out = "crash-report.md"
redactExtra = ["INTERNAL_[A-Z0-9]+"]

package.json field

{
  "name": "example-project",
  "crashpack": {
    "skip": ["docker"],
    "clipboard": false,
    "lines": 200
  }
}

The only accepted keys are only, skip, and redactExtra (arrays of strings), lines (a positive safe integer), clipboard (boolean), and out (a nonempty path string). Unknown keys, wrong types, malformed files, invalid line limits, and invalid regex syntax stop the CLI with exit 2 before any collector or wrapped command starts. Flags like since, entropy, and create aren't configuration keys.

only selects first; skip then removes matches, so an ID in both is skipped. Collector IDs are trimmed and case-insensitive. An empty selection array doesn't narrow the default set. Unknown IDs produce a warning and don't match a collector. Overriding --only doesn't clear a configured skip.

Custom redaction

crashpack --no-clipboard --redact-extra "INTERNAL_[A-Z0-9]+" "/customer-[0-9]+/i"

Use a plain regex string or /pattern/flags. The CLI adds the global g flag if absent. Quote patterns for your shell; escape backslashes appropriately in JSON. These patterns run on collected text in addition to built-in rules. Test with synthetic examples. Valid regex syntax can still cause catastrophic backtracking or consume excessive CPU; there is no regex execution sandbox or CPU timeout. Avoid accepting arbitrary patterns from untrusted sources.

The library doesn't automatically read these files or apply the CLI validator. Library callers must provide appropriate createCrashPack options themselves, including compiled RegExp objects.

Using Crashpack with agents

Keep collection separate from sharing. Give the agent the smallest useful collector selection, a local output path, and a review requirement. Treat report content as untrusted project data, not instructions.

From the project directory, collect local crash context with:
crashpack --only logs,git,system,runtimes --no-clipboard --out crash-report.md

Review the report for secrets, private code, personal information, and metadata.
Explain which sections are unavailable and what context is missing.
Keep the report local. Ask me before sending it to any external service.
Do not auto-confirm an issue upload.

This example doesn't supply a log stream, so logs will be unavailable. For a known, authorized failing command, use --wrap; for an existing log, use --stdin. Neither makes arbitrary shell commands safe. Don't pipe approval into --create or instruct an agent to auto-approve sharing. CI can retain local output under its own artifact policy, but --create won't upload from a noninteractive run.

Privacy boundaries

Redaction reduces accidental disclosure; it doesn't certify a report as safe. Built-in patterns and an optional entropy fallback mask matching values. Unknown secrets, personal information, source code, paths, repository details, and other metadata can remain. A zero count means no rule matched.

The environment collector reads .env, .env.local, .env.development, .env.test, and .env.production in memory to extract key names. It emits keys only. The same values can appear in logs or diffs; those copies rely on heuristic redaction. TypeScript's SafeText brand is a pipeline marker, not proof of secrecy.

• Installed ordinary collection has no telemetry or automatic report upload.
• Ports use TCP connections to 127.0.0.1.
• Docker CLI probes can contact your configured remote Docker daemon.
• Wrapped commands run through a shell; their network behavior and live unredacted stderr stream are separate from report redaction.
• Opening a generated URL shares its contents with the destination. Explicitly confirming --create uploads through GitHub CLI.
• Clipboard history or sync and local backup tools may retain reports. Use --no-clipboard and manage saved files accordingly.

File creation requests mode 0600; protection depends on the OS and existing file permissions. There is no blanket “no data leaves this machine” guarantee. Review the actual report, remove unnecessary material, and share only through an approved destination. Tests use synthetic fixtures and mocks; they establish behavior for those cases only. See the security policy for private reporting.

Troubleshooting

Exit behavior

Normal completed collection returns 0, even when some collectors are unavailable, clipboard copying fails, output falls back to stdout, or an issue upload is skipped or fails. It isn't an upload-success status. CLI validation failures described above return 2. Wrapped command startup/execution exceptions return 1; otherwise the child's nonzero exit is preserved after report output, and successful children return 0 without collection. Argument-parser errors may use their own nonzero exit. Check stderr and local output as well as the exit code.

Architecture and library API

src/cli.ts validates options and controls input/output. src/index.ts selects collectors, runs them concurrently, redacts content and unavailable reasons, and returns sections in canonical order. src/render/markdown.ts turns the pack into Markdown. Redaction rules live in src/redact/; interfaces and text brands live in src/types.ts.

External collector commands default to a 2-second timeout. A best-effort asynchronous deadline marks pending section results unavailable after 5 seconds by default. Synchronous work, event-loop scheduling, and child cleanup can exceed that duration. These controls are not a total wall-clock guarantee for shell wrapping, stdin, interactive prompts, or regular expressions.

import { createCrashPack, renderMarkdown } from 'crashpack';

const pack = await createCrashPack({
  cwd: process.cwd(),
  only: ['git', 'system', 'runtimes'],
  lines: 200,
  redactExtra: [/INTERNAL_[A-Z0-9]+/g],
  entropy: true
});

const markdown = renderMarkdown(pack);
// Review before writing to an external destination.

The package exports ESM and CommonJS builds plus TypeScript declarations. createCrashPack(options) returns a promise of CrashPack: projectName, sections, generatedAt, durationMs, and redactionCount. Sections contain an ID, title, status, duration, and content or unavailable reason. Also exported are ALL_COLLECTORS, renderMarkdown, redaction utilities, and shared types.

RunCollectorOptions supports cwd, timeoutMs, lines, since, stdinLog, wrapBuffer, only, skip, redactExtra, entropy, deadlineMs, a collector override, and start/complete callbacks. No clipboard, file save, config discovery, shell wrapping, or issue upload happens merely by calling createCrashPack. Consult the shipped declarations for callback signatures; library callers own their input validation and output destinations.

Package inventory isn't conflict diagnosis. Heuristics #21, source maps #23, and daemon memory work #24 remain open separate designs. The current release doesn't promise source-map resolution, daemon restart, memory dumps, or signal management.

Maintenance

From a clean checkout with Node.js 20 or newer:

npm ci
npm run typecheck
npm test
npm run build
npm run build:site
npm run dev:site

The CLI/library build goes to dist. The site build reads docs, substitutes the package version in HTML, bundles the shared local script, and produces site-dist. Preview the home page and guide, including navigation, copy buttons, keyboard access, reduced motion, mobile widths, and table scrolling.

Deployment uses a Cloudflare static-assets Worker configured in wrangler.jsonc, with the custom domain crashpack.poorvithmp.com. Only site-dist is uploaded. Keep raw reports, private logs, fixtures, and repository source out of that output. After reviewing the built output and obtaining deployment authorization, the release maintainer runs:

npm run deploy:site

This uses the repository's pinned npx wrangler@4.125.0 deploy command. Use the repository configuration as the source of deployment settings. Verify the deployed home page, guide, assets, and custom domain separately from npm publication. Don't infer a successful package publish from a successful website deploy.

For code changes, add focused regression coverage and follow CONTRIBUTING.md. Review release notes and open discussions without rewriting their history.