Command Guide

Command Guide

This page explains each CLI entry point and the common options.

Default Cleaner

ctxclean [OPTIONS] [INPUT]

Input can be:

• a file path
• a directory path
• - for explicit stdin
• omitted when stdin is piped

Examples:

ctxclean README.md
ctxclean fixtures/dirty_html_article.html --mode standard --format markdown
ctxclean - --format json < pasted-log.txt

GitHub Actions Log Cleaner

ctxclean gha failed-log.txt --max-tokens 8000 --format markdown

gha is an alias tuned for CI logs. It defaults to aggressive cleanup and keeps failure lines, failed test names, stack trace signal, timestamps near failures, and final summaries.

Repository Context Packer

ctxclean repo . --max-tokens 12000 --format markdown

The repo mode scans a directory while respecting:

• .gitignore
• .ctxcleanignore
• generated directory defaults
• sensitive path defaults
• aggregate byte limits
• secret redaction

Report Mode

ctxclean report ./project
ctxclean report build.log --max-tokens 8000 --format json

Reports include:

• input tokens
• output tokens
• tokens saved
• compression ratio
• biggest noise sources
• removed section summary
• warnings
• recommended command

MCP Server Mode

ctxclean mcp

MCP mode exposes tools over newline-delimited JSON-RPC on stdio:

• contextclean_clean
• contextclean_report

Use it with MCP clients that support stdio servers.

ctxrun

ctxrun --max-tokens 8000 npm test
ctxrun --format markdown pytest

ctxrun runs a local command.

• If the command succeeds, stdout and stderr are passed through.
• If the command fails, captured output is cleaned with ContextClean.
• The child exit code is preserved.
• --timeout-seconds exits 124 when the child times out.
• --capture-limit-bytes limits retained failed-output bytes per stream while still draining the full pipe.

Common Options

Option	Description
--output, --out	Write output to a file.
--max-tokens	Hard output token ceiling.
--fit	Use a known model budget preset.
--mode	light, standard, or aggressive.
--format	text, markdown, or json.
--strip-comments	Remove obvious code comment lines.
--include-sensitive	Explicitly include sensitive paths.
--redact-secrets	Keep default redaction enabled explicitly.
--no-redact-secrets	Disable defensive redaction.
--dry-run	Print without writing output files.
--force	Overwrite output files.
--quiet	Suppress non-error diagnostics.
--verbose	Print extra diagnostics to stderr.

Modes

Mode	Behavior
light	Minimal cleanup. Good when preserving structure matters most.
standard	Default balance for common HTML, logs, and mixed text.
aggressive	Heavier boilerplate and noise removal. Good for CI logs and scraped pages.