Codemap.Cli 1.0.5

codemap

codemap scans codebases and turns selected files into focused, deterministic context for AI tools and developers. It filters files, can include Git history, enforces token and size limits, and excludes files with security findings before producing the output.

Contents

• Installation
• Features
• How to run
• Requirements
• Command reference
• Configuration
• Advanced capabilities
• Support
• Contribution

Installation

codemap is distributed as a .NET tool. Install the published package globally with:

dotnet tool install --global Codemap.Cli

Then run it from any directory with codemap.

Running codemap without options scans the current directory. Change into the repository directory before running it.

Features

How to Run

codemap's main workflow is simple: choose a source directory, select an output format, and write the generated repository context to a file. The examples below focus on core commands.

❔ Help

Use the built-in help whenever you need to check available commands and options:

codemap --help

🔀 Include and Exclude

Use --include to select files and --exclude to remove paths from that selection:

codemap \
	--include "src/**/*.cs,README.md" \
	--exclude "**/bin/**,**/obj/**" \
	--format markdown \
	--output source-context.md

codemap also reads .gitignore and .ignore automatically.

The same selection can use short aliases: codemap -i "src/**/*.cs" -e "**/bin/**,**/obj/**" -f markdown -o source-context.md.

🛡️ Security Check

Use DevSkim to exclude files with actionable security findings before they enter the generated context:

codemap \
	--security-check \
	--format markdown \
	--output reviewed-context.md

codemap reports excluded files in the terminal. Node.js and npm are not required.

📝 Format

The default format is Markdown. Use --format to choose another output format when needed:

# Human- and AI-friendly document
codemap --format markdown --output repository.md

# Structured data for another program
codemap --format json --output repository.json

# XML or simple text output
codemap --format xml --output repository.xml
codemap --format plain --output repository.txt

🌐 Remote

codemap can clone a repository and pack a selected branch:

codemap \
	--remote microsoft/generative-ai-for-beginners \
	--remote-branch main \
	--format markdown \
	--output remote-context.md

The same command accepts a complete Git URL. Git must be installed and available on PATH for remote repositories and Git metadata.

Requirements

• .NET SDK 10 or newer.
• Git only when using --remote, --include-diffs, or --include-logs.
• Node.js and npm are not required. Security scanning is implemented with DevSkim for .NET.

Command Reference

General form:

codemap [options]
codemap stdout [options]
codemap clipboard [options]
codemap -s [options]
codemap -c [options]

Show the built-in command reference at any time:

codemap --help

Boolean options are enabled by writing the flag.

Configuration

Configuration uses JSON. codemap automatically loads codemap.json or codemap.config.json from the source root. Use --config to select another file.

{
	"outputPath": "artifacts/repository.md",
	"format": "Markdown",
	"includePatterns": ["**/*.cs", "**/*.md"],
	"excludePatterns": ["**/test-data/**"],
	"includeFileSummary": true,
	"includeDirectoryStructure": true,
	"showLineNumbers": false,
	"removeComments": true,
	"removeEmptyLines": true,
	"enableSecurityCheck": true,
	"maxFileSizeBytes": 500000,
	"tokenBudget": 12000,
	"includeGitDiffs": false,
	"includeGitLogs": true,
	"gitLogCount": 10,
	"splitOutputBytes": 200000
}

Command-line values override configuration values. For list options such as --include and --exclude, the command-line value replaces the configured list.

Advanced Capabilities

Exclude

Use .ignore to keep repository-specific files out of generated context, such as local notes, logs, fixtures, or generated output. Place it in the source root and add one glob per line; codemap also reads .gitignore, supports comments and ordered rules, and uses ! to re-include a matching path. Common generated directories are excluded automatically.

Security

Use --security-check when the source may contain credentials, unsafe cryptography, or other known security problems. codemap scans original UTF-8 files before cleanup, omits files with actionable DevSkim findings instead of stopping the entire pack, and reports excluded paths in the console and result model.

Tokens

Token counts help estimate how much context an AI tool will receive. codemap reports per-file and final-output counts using the GPT-4-compatible cl100k_base encoding; use --token-budget to reject oversized output, --max-file-size to skip large files, or --split-output to create smaller parts.

Workflow

Use --remote when the repository is not available locally; codemap clones it into a temporary directory and packs the selected branch. For repository history, --include-diffs adds current changes and --include-logs adds recent commits. --watch monitors a local source tree and reports changes so you can run codemap again.

🌟 Support

If you like my work, feel free to:

• ⭐ this repository. And we will be happy together 😃

Thanks a bunch for supporting me!

🤝 Contribution

Thanks to all contributors, you're awesome and this wouldn't be possible without you! The goal is to build a categorized, community-driven collection of very well-known resources.

Please follow this contribution guideline to submit a pull request or create the issue.