FailPackDocumentation

FailPack CLI documentation

FailPack is a local-first terminal app and command-line toolkit for capturing failures, syncing report artifacts, generating tests and running focused bug or security agents.

Current package

@failpack/cli

Install FailPack

Install globally, then run FailPack inside the repository you want to debug.

npm install -g @failpack/cli
failpack

First run asks whether you trust the current repo. After confirmation, FailPack creates local config and keeps sensitive runtime data out of committed files.

Interactive CLI

Running only failpack opens the TUI: project status, account state, Cloud state, recent activity, command suggestions and guided actions without memorizing flags.

run <command>Run and capture a command from the TUI.

reportCreate or inspect the latest local report.

statusReview local report versions and fixed state.

agent bugStart focused bug analysis when Cloud and plan allow it.

agent securityRun a security-focused investigation.

cloud syncPush/pull current project report history.

workspace switchChange the active Cloud workspace.

modelChoose the workspace agent profile allowed by plan.

First report

Capture a failing build or test command. FailPack records output, git state, environment summary and project metadata into a local package.

failpack capture --cmd "npm run build"
failpack capture --cmd "npm test" --project ./my-app --fail-on-command-error

Capture options

Tune what gets captured, how much output is preserved and how the command should affect exit codes.

--cmd "npm run build"Command to execute and capture.

--project ./my-appProject directory, useful from monorepos or scripts.

--include-sourceInclude a limited source snapshot when plan and settings allow it.

--max-log-lines 800Keep the last N output lines.

--timeout 600Stop long-running commands after N seconds.

--output .failpack/reportsLocal report output directory.

--overwriteReplace the latest local version instead of creating a new one.

--fail-on-command-errorReturn the captured command exit code when it fails.

--no-redactDisable local redaction only when you explicitly accept the risk.

Reports and files

FailPack writes useful local artifacts first. Cloud upload can later attach metadata, manifests and private artifact references without making storage public.

failpack-report.md

Human-readable failure report with command, environment, status and summary.

failpack-ai-prompt.md

Prompt-shaped context for coding agents, AI assistants and issue triage.

failpack-context.json

Structured context used by Cloud, dashboards, automation and analysis.

failpack-bundle.zip

Optional portable bundle with report files and selected safe artifacts.

.failpackrc.json

Project configuration with Cloud project id. Commit safe config, never secrets.

Cloud artifacts

Private R2-backed report artifacts streamed through authenticated backend access.

failpack report --github
failpack status
failpack fix v3
failpack unfix v3
failpack clean --yes

Cloud sync

Cloud stores report metadata and private artifacts for the active workspace. Auto-sync is controlled per repository and uses the project id in local FailPack config.

Project historyEach repo can sync its own report versions, status and artifacts.

Private accessArtifacts are loaded through authenticated backend access checks, not public bucket URLs.

failpack login
failpack cloud sync on
failpack cloud sync
failpack cloud list
failpack cloud open
failpack cloud rename "Frontend app"

Workspaces

Use one account across personal and team workspaces. The selected workspace controls Cloud uploads, dashboard data, plan access and agent budgets.

failpack workspace list
failpack workspace current
failpack workspace switch
failpack workspace rename "Acme Engineering" --company "Acme"

Agent mode

Agent mode requires Cloud login and a plan that includes the selected mode. It runs locally in the current repo, asks the backend for structured tool calls, and never leaves the project root.

agent bug finds likely failures and practical fixes.

agent security checks injection, auth, secrets, XSS and unsafe tooling paths.

agent chat is available on higher plans for interactive engineering help.

failpack agent bug
failpack agent security --prompt "Audit auth and artifact access"
failpack agent chat
failpack model

Test generation

Standard mode can scaffold local tests. Expert mode uses Cloud-backed AI generation, writes test files and runs the detected test command unless you disable execution.

failpack test
failpack test --framework vitest --limit 8
failpack test --expert --prompt "Cover auth token rotation"
failpack test --expert --no-run

AI client setup

Generate repository instructions so other coding agents know to use FailPack reports first and respect local safety boundaries.

failpack ai-setup --all
failpack mcp

Repository guidesWrites AI.md, AGENTS.md, Cursor, Windsurf and Copilot instructions.

MCP readyCan generate Claude desktop MCP config and run the FailPack MCP server.

Command reference

The current public CLI surface in one place. Use --json on supported commands for automation.

failpackOpen the interactive terminal app.

failpack initTrust and initialize the current repository.

failpack captureRun a command and create a report package.

failpack aiCreate an AI prompt from local project context.

failpack reportCreate Markdown, GitHub or Discord-ready report output.

failpack statusShow local report history and version state.

failpack fix / unfixMark report versions as fixed or unfixed.

failpack doctorCheck local environment and project health.

failpack cleanRemove old local reports.

failpack login / logout / whoamiManage Cloud account and CLI device session.

failpack cloud uploadUpload the latest report or a selected context JSON.

failpack cloud sync on/off/statusEnable, disable or inspect project Cloud sync.

failpack cloud list/open/delete/renameManage Cloud projects and reports.

failpack workspace list/current/switch/renameUse personal or team workspaces from the CLI.

failpack analyzeAnalyze the latest or selected Cloud report.

failpack securityRun Cloud-backed security analysis.

failpack agent bug/security/chatRun plan-aware local-tool agent mode.

failpack test --expertGenerate standard or Expert AI tests and run them.

failpack modelChoose Standard, Deeper or Ultra agent profile when allowed.

failpack ai-setup --allWrite AI.md, AGENTS.md, Cursor, Windsurf, Copilot and Claude MCP config.

failpack mcpStart the FailPack MCP server on stdio.

failpack upgradeOpen billing and plan upgrade options.

Security model

FailPack is built to collect useful debugging context without turning reports into credential dumps.

Common keys, tokens and credentials are redacted before reports are saved or uploaded.

.env files, private keys and sensitive paths are excluded by default.

Private Cloud artifacts are served only after auth, workspace and report access checks.

Agent tools are constrained to the current repository and risky commands are blocked.

Start from the terminal.

Install FailPack, run failpack, capture one failure and review the generated report before sharing.

Back to product