Skip to content

Improve CLI help text clarity and accuracy #831

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yamadashy merged 4 commits into from
Sep 12, 2025
Merged

Improve CLI help text clarity and accuracy #831

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c0bda85
docs(cli): Improve help text clarity and accuracy
yamadashy Sep 12, 2025
f0a5808
docs(website): Update CLI documentation for all languages
yamadashy Sep 12, 2025
f5a90d6
fix(lint): Apply biome formatting to CLI options
yamadashy Sep 12, 2025
702f7f1
fix(cli): improve help text consistency and input validation
yamadashy Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 38 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -531,60 +531,60 @@ Instruction
### Command Line Options

#### Basic Options
- `-v, --version`: Show tool version
- `-v, --version`: Show version information and exit

#### CLI Input/Output Options
- `--verbose`: Enable verbose logging
- `--quiet`: Disable all output to stdout
- `--stdout`: Output to stdout instead of writing to a file (cannot be used with `--output` option)
- `--stdin`: Read file paths from stdin instead of discovering files automatically
- `--copy`: Additionally copy generated output to system clipboard
- `--token-count-tree [threshold]`: Display file tree with token count summaries (optional: minimum token count threshold). Useful for identifying large files and optimizing token usage for AI context limits
- `--top-files-len <number>`: Number of top files to display in the summary
- `--verbose`: Enable detailed debug logging (shows file processing, token counts, and configuration details)
- `--quiet`: Suppress all console output except errors (useful for scripting)
- `--stdout`: Write packed output directly to stdout instead of a file (suppresses all logging)
- `--stdin`: Read file paths from stdin, one per line (specified files are processed directly)
- `--copy`: Copy the generated output to system clipboard after processing
- `--token-count-tree [threshold]`: Show file tree with token counts; optional threshold to show only files with ≥N tokens (e.g., --token-count-tree 100)
- `--top-files-len <number>`: Number of largest files to show in summary (default: 5, e.g., --top-files-len 20)

#### Repomix Output Options
- `-o, --output <file>`: Specify the output file name
- `--style <style>`: Specify the output style (`xml`, `markdown`, `plain`)
- `--parsable-style`: Enable parsable output based on the chosen style schema. Note that this can increase token count.
- `--compress`: Perform intelligent code extraction, focusing on essential function and class signatures to reduce token count
- `--output-show-line-numbers`: Show line numbers in the output
- `--no-file-summary`: Disable file summary section output
- `--no-directory-structure`: Disable directory structure section output
- `--no-files`: Disable files content output (metadata-only mode)
- `--remove-comments`: Remove comments from supported file types
- `--remove-empty-lines`: Remove empty lines from the output
- `--truncate-base64`: Enable truncation of base64 data strings
- `--header-text <text>`: Custom text to include in the file header
- `--instruction-file-path <path>`: Path to a file containing detailed custom instructions
- `--include-empty-directories`: Include empty directories in the output
- `--no-git-sort-by-changes`: Disable sorting files by git change count (enabled by default)
- `--include-diffs`: Include git diffs in the output (includes both work tree and staged changes separately)
- `--include-logs`: Include git logs in the output (includes commit history with dates, messages, and file paths)
- `--include-logs-count <count>`: Number of git log commits to include (default: 50)
- `-o, --output <file>`: Output file path (default: repomix-output.xml, use "-" for stdout)
- `--style <style>`: Output format: xml, markdown, or plain (default: xml)
- `--parsable-style`: Escape special characters to ensure valid XML/Markdown (needed when output contains code that breaks formatting)
- `--compress`: Extract essential code structure (classes, functions, interfaces) using Tree-sitter parsing
- `--output-show-line-numbers`: Prefix each line with its line number in the output
- `--no-file-summary`: Omit the file summary section from output
- `--no-directory-structure`: Omit the directory tree visualization from output
- `--no-files`: Generate metadata only without file contents (useful for repository analysis)
- `--remove-comments`: Strip all code comments before packing
- `--remove-empty-lines`: Remove blank lines from all files
- `--truncate-base64`: Truncate long base64 data strings to reduce output size
- `--header-text <text>`: Custom text to include at the beginning of the output
- `--instruction-file-path <path>`: Path to file containing custom instructions to include in output
- `--include-empty-directories`: Include folders with no files in directory structure
- `--no-git-sort-by-changes`: Don't sort files by git change frequency (default: most changed files first)
- `--include-diffs`: Add git diff section showing working tree and staged changes
- `--include-logs`: Add git commit history with messages and changed files
- `--include-logs-count <count>`: Number of recent commits to include with --include-logs (default: 50)

#### File Selection Options
- `--include <patterns>`: List of include patterns (comma-separated)
- `-i, --ignore <patterns>`: Additional ignore patterns (comma-separated)
- `--no-gitignore`: Disable .gitignore file usage
- `--no-default-patterns`: Disable default patterns
- `--include <patterns>`: Include only files matching these glob patterns (comma-separated, e.g., "src/**/*.js,*.md")
- `-i, --ignore <patterns>`: Additional patterns to exclude (comma-separated, e.g., "*.test.js,docs/**")
- `--no-gitignore`: Don't use .gitignore rules for filtering files
- `--no-default-patterns`: Don't apply built-in ignore patterns (node_modules, .git, build dirs, etc.)

#### Remote Repository Options
- `--remote <url>`: Process a remote Git repository
- `--remote-branch <name>`: Specify the remote branch name, tag, or commit hash (defaults to repository default branch)
- `--remote <url>`: Clone and pack a remote repository (GitHub URL or user/repo format)
- `--remote-branch <name>`: Specific branch, tag, or commit to use (default: repository's default branch)

#### Configuration Options
- `-c, --config <path>`: Path to a custom config file
- `--init`: Create config file
- `--global`: Use global config
- `-c, --config <path>`: Use custom config file instead of repomix.config.json
- `--init`: Create a new repomix.config.json file with defaults
- `--global`: With --init, create config in home directory instead of current directory

#### Security Options
- `--no-security-check`: Disable security check
- `--no-security-check`: Skip scanning for sensitive data like API keys and passwords

#### Token Count Options
- `--token-count-encoding <encoding>`: Specify token count encoding used by OpenAI's [tiktoken](https://github.com/openai/tiktoken) tokenizer (e.g., `o200k_base` for GPT-4o, `cl100k_base` for GPT-4/3.5). See [tiktoken model.py](https://github.com/openai/tiktoken/blob/main/tiktoken/model.py#L24) for encoding details.
- `--token-count-encoding <encoding>`: Tokenizer model for counting: o200k_base (GPT-4o), cl100k_base (GPT-3.5/4), etc. (default: o200k_base)

#### MCP
- `--mcp`: Run as a [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server
- `--mcp`: Run as Model Context Protocol server for AI tool integration

#### Examples

Expand Down
129 changes: 82 additions & 47 deletions src/cli/cliRun.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,82 +52,117 @@ export const run = async () => {
.argument('[directories...]', 'list of directories to process', ['.'])
// Basic Options
.optionsGroup('Basic Options')
.option('-v, --version', 'show version information')
.option('-v, --version', 'Show version information and exit')
// CLI Input/Output Options
.optionsGroup('CLI Input/Output Options')
.addOption(new Option('--verbose', 'enable verbose logging for detailed output').conflicts('quiet'))
.addOption(new Option('--quiet', 'disable all output to stdout').conflicts('verbose'))
.addOption(new Option('--stdout', 'output to stdout instead of writing to a file').conflicts('output'))
.option('--stdin', 'read file list from stdin')
.option('--copy', 'copy generated output to system clipboard')
.addOption(
new Option(
'--verbose',
'Enable detailed debug logging (shows file processing, token counts, and configuration details)',
).conflicts('quiet'),
)
.addOption(
new Option('--quiet', 'Suppress all console output except errors (useful for scripting)').conflicts('verbose'),
)
.addOption(
new Option(
'--stdout',
'Write packed output directly to stdout instead of a file (suppresses all logging)',
).conflicts('output'),
)
.option('--stdin', 'Read file paths from stdin, one per line (specified files are processed directly)')
.option('--copy', 'Copy the generated output to system clipboard after processing')
.option(
'--token-count-tree [threshold]',
'display file tree with token count summaries (optional: minimum token count threshold)',
'Show file tree with token counts; optional threshold to show only files with ≥N tokens (e.g., --token-count-tree 100)',
(value: string | boolean) => {
if (typeof value === 'string') {
const parsed = Number.parseInt(value, 10);
if (Number.isNaN(parsed)) {
throw new RepomixError(`Invalid token count threshold: '${value}'. Must be a valid number.`);
if (!/^\d+$/.test(value)) {
throw new RepomixError(`Invalid token count threshold: '${value}'. Must be a non-negative integer.`);
}
return parsed;
return Number(value);
}
return value;
},
)
.option('--top-files-len <number>', 'specify the number of top files to display', Number.parseInt)
.option(
'--top-files-len <number>',
'Number of largest files to show in summary (default: 5, e.g., --top-files-len 20)',
(v: string) => {
if (!/^\d+$/.test(v)) {
throw new RepomixError(`Invalid number for --top-files-len: '${v}'. Must be a non-negative integer.`);
}
return Number(v);
},
)
// Repomix Output Options
.optionsGroup('Repomix Output Options')
.option('-o, --output <file>', 'specify the output file name')
.option('--style <type>', 'specify the output style (xml, markdown, plain)')
.option('--parsable-style', 'by escaping and formatting, ensure the output is parsable as a document of its type')
.option('--compress', 'perform code compression to reduce token count')
.option('--output-show-line-numbers', 'add line numbers to each line in the output')
.option('--no-file-summary', 'disable file summary section output')
.option('--no-directory-structure', 'disable directory structure section output')
.option('--no-files', 'disable files content output (metadata-only mode)')
.option('--remove-comments', 'remove comments')
.option('--remove-empty-lines', 'remove empty lines')
.option('--truncate-base64', 'enable truncation of base64 data strings')
.option('--header-text <text>', 'specify the header text')
.option('--instruction-file-path <path>', 'path to a file containing detailed custom instructions')
.option('--include-empty-directories', 'include empty directories in the output')
.option('--no-git-sort-by-changes', 'disable sorting files by git change count')
.option('-o, --output <file>', 'Output file path (default: repomix-output.xml, use "-" for stdout)')
.option('--style <type>', 'Output format: xml, markdown, or plain (default: xml)')
.option(
'--include-diffs',
'include git diffs in the output (includes both work tree and staged changes separately)',
'--parsable-style',
'Escape special characters to ensure valid XML/Markdown (needed when output contains code that breaks formatting)',
)
.option(
'--include-logs',
'include git logs in the output (includes commit history with dates, messages, and file paths)',
'--compress',
'Extract essential code structure (classes, functions, interfaces) using Tree-sitter parsing',
)
.option('--output-show-line-numbers', 'Prefix each line with its line number in the output')
.option('--no-file-summary', 'Omit the file summary section from output')
.option('--no-directory-structure', 'Omit the directory tree visualization from output')
.option('--no-files', 'Generate metadata only without file contents (useful for repository analysis)')
.option('--remove-comments', 'Strip all code comments before packing')
.option('--remove-empty-lines', 'Remove blank lines from all files')
.option('--truncate-base64', 'Truncate long base64 data strings to reduce output size')
.option('--header-text <text>', 'Custom text to include at the beginning of the output')
.option('--instruction-file-path <path>', 'Path to file containing custom instructions to include in output')
.option('--include-empty-directories', 'Include folders with no files in directory structure')
.option(
'--no-git-sort-by-changes',
"Don't sort files by git change frequency (default: most changed files first)",
)
.option('--include-diffs', 'Add git diff section showing working tree and staged changes')
.option('--include-logs', 'Add git commit history with messages and changed files')
.option(
'--include-logs-count <count>',
'Number of recent commits to include with --include-logs (default: 50)',
(v: string) => {
if (!/^\d+$/.test(v)) {
throw new RepomixError(`Invalid number for --include-logs-count: '${v}'. Must be a non-negative integer.`);
}
return Number(v);
},
)
.option('--include-logs-count <count>', 'number of git log commits to include (default: 50)', Number.parseInt)
// File Selection Options
.optionsGroup('File Selection Options')
.option('--include <patterns>', 'list of include patterns (comma-separated)')
.option('-i, --ignore <patterns>', 'additional ignore patterns (comma-separated)')
.option('--no-gitignore', 'disable .gitignore file usage')
.option('--no-default-patterns', 'disable default patterns')
// Remote Repository Options
.optionsGroup('Remote Repository Options')
.option('--remote <url>', 'process a remote Git repository')
.option(
'--remote-branch <name>',
'specify the remote branch name, tag, or commit hash (defaults to repository default branch)',
'--include <patterns>',
'Include only files matching these glob patterns (comma-separated, e.g., "src/**/*.js,*.md")',
)
.option('-i, --ignore <patterns>', 'Additional patterns to exclude (comma-separated, e.g., "*.test.js,docs/**")')
.option('--no-gitignore', "Don't use .gitignore rules for filtering files")
.option('--no-default-patterns', "Don't apply built-in ignore patterns (node_modules, .git, build dirs, etc.)")
// Remote Repository Options
.optionsGroup('Remote Repository Options')
.option('--remote <url>', 'Clone and pack a remote repository (GitHub URL or user/repo format)')
.option('--remote-branch <name>', "Specific branch, tag, or commit to use (default: repository's default branch)")
// Configuration Options
.optionsGroup('Configuration Options')
.option('-c, --config <path>', 'path to a custom config file')
.option('--init', 'initialize a new repomix.config.json file')
.option('--global', 'use global configuration (only applicable with --init)')
.option('-c, --config <path>', 'Use custom config file instead of repomix.config.json')
.option('--init', 'Create a new repomix.config.json file with defaults')
.option('--global', 'With --init, create config in home directory instead of current directory')
// Security Options
.optionsGroup('Security Options')
.option('--no-security-check', 'disable security check')
.option('--no-security-check', 'Skip scanning for sensitive data like API keys and passwords')
// Token Count Options
.optionsGroup('Token Count Options')
.option('--token-count-encoding <encoding>', 'specify token count encoding (e.g., o200k_base, cl100k_base)')
.option(
'--token-count-encoding <encoding>',
'Tokenizer model for counting: o200k_base (GPT-4o), cl100k_base (GPT-3.5/4), etc. (default: o200k_base)',
)
// MCP
.optionsGroup('MCP')
.option('--mcp', 'run as a MCP server')
.option('--mcp', 'Run as Model Context Protocol server for AI tool integration')
.action(commanderActionEndpoint);

// Custom error handling function
Expand Down
20 changes: 11 additions & 9 deletions website/client/src/de/guide/command-line-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@
- `--stdin`: Dateipfade von stdin lesen statt Dateien automatisch zu entdecken
- `--copy`: Generierte Ausgabe zusätzlich in die Systemzwischenablage kopieren
- `--token-count-tree [threshold]`: Dateibaum mit Token-Anzahl-Zusammenfassungen anzeigen (optional: minimale Token-Anzahl-Schwelle). Nützlich zur Identifizierung großer Dateien und Optimierung der Token-Nutzung für KI-Kontextlimits
- `--top-files-len <number>`: Anzahl der Top-Dateien in der Zusammenfassung
- `--top-files-len <number>`: Anzahl der größten Dateien in der Zusammenfassung (Standard: 5, z.B. --top-files-len 20)

## Repomix-Ausgabeoptionen
- `-o, --output <file>`: Ausgabedateiname angeben
- `--style <style>`: Ausgabestil angeben (`xml`, `markdown`, `plain`)
- `-o, --output <file>`: Ausgabedateipfad (Standard: repomix-output.xml, "-" für stdout)
- `--style <type>`: Ausgabeformat: xml, markdown oder plain (Standard: xml)
- `--parsable-style`: Parsbare Ausgabe basierend auf dem gewählten Stil-Schema aktivieren. Beachten Sie, dass dies die Token-Anzahl erhöhen kann.
- `--compress`: Intelligente Code-Extraktion durchführen, die sich auf wesentliche Funktions- und Klassensignaturen konzentriert, um die Token-Anzahl zu reduzieren
- `--output-show-line-numbers`: Zeilennummern in der Ausgabe anzeigen
Expand Down Expand Up @@ -48,20 +48,22 @@
- `--global`: Globale Konfiguration verwenden

## Sicherheitsoptionen
- `--no-security-check`: Sicherheitsprüfung deaktivieren (Standard: `true`)
- `--no-security-check`: Scannen nach sensiblen Daten wie API-Schlüsseln und Passwörtern überspringen

## Token-Anzahl-Optionen
- `--token-count-encoding <encoding>`: Token-Anzahl-Kodierung angeben, die von OpenAIs [tiktoken](https://github.com/openai/tiktoken) Tokenizer verwendet wird (z.B. `o200k_base` für GPT-4o, `cl100k_base` für GPT-4/3.5). Siehe [tiktoken model.py](https://github.com/openai/tiktoken/blob/main/tiktoken/model.py#L24) für Kodierungsdetails.
- `--token-count-encoding <encoding>`: Tokenizer-Modell für Zählung: o200k_base (GPT-4o), cl100k_base (GPT-3.5/4), etc. (Standard: o200k_base)

## MCP-Optionen
- `--mcp`: Als Model Context Protocol Server für AI-Tool-Integration ausführen

## Beispiele

```bash
# Grundlegende Nutzung
repomix

# Benutzerdefinierte Ausgabe
repomix -o output.xml --style xml
# Benutzerdefinierte Ausgabedatei und Format
repomix -o my-output.xml --style xml

# Ausgabe an stdout
repomix --stdout > custom-output.txt
Expand All @@ -72,8 +74,8 @@ repomix --stdout | llm "Bitte erklären Sie, was dieser Code macht."
# Benutzerdefinierte Ausgabe mit Komprimierung
repomix --compress

# Spezifische Dateien verarbeiten
repomix --include "src/**/*.ts" --ignore "**/*.test.ts"
# Spezifische Dateien mit Mustern verarbeiten
repomix --include "src/**/*.ts,*.md" --ignore "*.test.js,docs/**"

# Remote-Repository mit Branch
repomix --remote https://github.com/user/repo/tree/main
Expand Down
Loading
Loading