# How to Use Freebuff for Code Formatting: CLI Guide and Architecture > Learn how to use Freebuff for code formatting with our CLI guide. Freebuff integrates AI-powered formatting and sanitizes output from tools like Prettier for safe display. - Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff) - Tags: how-to-guide - Published: 2026-08-21 --- **Freebuff provides an AI-powered code formatting interface that invokes external formatters like Prettier through a unified CLI, automatically sanitizing and truncating output for safe display.** Freebuff is an open-source AI coding assistant framework that includes a built-in code formatting pipeline. The formatting tool processes your files through the `freebuff format` command while streaming sanitized, length-limited results back to your terminal. This guide explains how to use the CLI effectively and explores the underlying architecture implemented in the `CodebuffAI/freebuff` repository. ## Basic Usage with the Freebuff CLI To format code using Freebuff, invoke the formatter through the CLI entry point defined in [`freebuff/cli/release.ts`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/release.ts). The tool accepts file paths, directories, or glob patterns as arguments. Install Freebuff globally (if not already installed): ```bash bun install -g @codebuff/freebuff ``` Run the formatter on a single file or entire project: ```bash # Format a specific file freebuff format src/index.ts # Format recursively from current directory freebuff format . ``` The CLI dispatches to the `format` tool definition located in [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts), which specifies the input schema, output type, and termination semantics including the `endsAgentStep` flag that signals completion of the formatting operation. ## CLI Options and Flags Freebuff supports several flags to control formatting behavior and output visibility. ### Dry-Run Mode and Diff Preview Use `--dry-run` to preview changes without modifying files. This flag displays the diff through the truncation-safe output handler: ```bash freebuff format --dry-run src/utils.ts ``` The runtime implementation in [`sdk/src/tools/run-terminal-command.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/tools/run-terminal-command.ts) executes the formatter as a child process and captures the diff output. When displaying results, the `format()` method automatically truncates content exceeding the character limit and inserts the `[...TRUNCATED DUE TO LENGTH...]` sentinel to maintain UI responsiveness. ### Custom Configuration Files Point to custom formatter configurations using the `--config` flag: ```bash freebuff format . --config .prettierrc.cjs ``` The CLI passes this configuration path through to the underlying formatter process. According to the tool schema in [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts), the formatter accepts configuration overrides while maintaining the same output sanitization rules. ### Output Length Limiting Control the maximum streamed output size with `--max-output`: ```bash freebuff format src/ --max-output 5000 ``` This parameter directly configures the truncation threshold in the `format()` method, ensuring that large formatting jobs do not flood the terminal or AI context windows. ## Architecture and Implementation Details The formatting pipeline consists of three coordinated components across the codebase. ### Tool Definition in agents/types/tools.ts The `format` tool is formally defined in [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts). This file declares the tool's interface, including input parameters (file paths, config options), return type specifications, and the `endsAgentStep` boolean that marks the completion of a formatting step in the agent's execution loop. ### Runtime Execution in sdk/src/tools/run-terminal-command.ts The actual execution logic resides in [`sdk/src/tools/run-terminal-command.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/tools/run-terminal-command.ts). The `format()` method in this file: - Spawns the external formatter process (Prettier, ESLint --fix, or custom) - Captures stdout and stderr streams - Sanitizes ANSI color codes for safe display - Applies length truncation with the `[...]` marker - Returns a structured JSON response containing the formatted output or error details ### CLI Entry Point in freebuff/cli/release.ts Argument parsing and command dispatch occur in [`freebuff/cli/release.ts`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/release.ts). This file maps the `format` subcommand to the runtime tool invocation, handling path resolution, flag validation, and error propagation back to the user. ### Output Formatting in common/src/util/format-code-search.ts Multi-file diff formatting and pretty-printing utilities are provided by [`common/src/util/format-code-search.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/format-code-search.ts). This helper module supports the presentation layer by structuring output when formatting multiple files simultaneously, ensuring consistent diff formatting across the CLI output. ## Practical Examples Format a single file with verbose output: ```bash freebuff format src/components/Button.tsx ``` Preview changes across the entire codebase before applying: ```bash freebuff format --dry-run . --config ./prettier.config.js ``` Format with strict output limits for AI context windows: ```bash freebuff format src/lib/ --max-output 2000 --dry-run ``` ## Summary - **Use `freebuff format `** to invoke the AI-powered formatter on files or directories, with the CLI entry point located in [`freebuff/cli/release.ts`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/release.ts). - **Preview changes safely** by adding `--dry-run` to see diffs without writing files, with output sanitized and truncated by the `format()` method in [`sdk/src/tools/run-terminal-command.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/tools/run-terminal-command.ts). - **Customize behavior** through `--config` for formatter settings and `--max-output` for length limits, as defined in the tool schema at [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts). - **Multi-file support** leverages [`common/src/util/format-code-search.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/format-code-search.ts) for structured diff presentation when formatting entire projects. ## Frequently Asked Questions ### What formatter engine does Freebuff use by default? According to the [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts) schema and runtime implementation, Freebuff defaults to Prettier for JavaScript/TypeScript files, though the architecture supports any external formatter that accepts file paths via CLI arguments. You can override the engine by specifying a custom executable through the `--config` flag or modifying the tool definition. ### How does Freebuff handle large formatting outputs? The `format()` method in [`sdk/src/tools/run-terminal-command.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/tools/run-terminal-command.ts) implements automatic truncation. When output exceeds the default or user-specified character limit (set via `--max-output`), the system inserts a `[...TRUNCATED DUE TO LENGTH...]` marker and discards remaining content to protect terminal performance and AI context window limits. ### Where is the formatting tool defined in the source code? The tool interface is defined in [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts), which specifies the `format` tool's parameters, return types, and the `endsAgentStep` termination flag. The runtime implementation that executes the actual formatting command resides in [`sdk/src/tools/run-terminal-command.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/tools/run-terminal-command.ts), while the CLI wrapper is found in [`freebuff/cli/release.ts`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/release.ts). ### Can I format multiple files with different configurations? Yes. Invoke `freebuff format` multiple times with different `--config` flags targeting specific directories, or use a single command on a parent directory. The [`common/src/util/format-code-search.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/format-code-search.ts) utility handles the aggregation and display of multi-file results, though each formatting operation respects the configuration file found in its target path or specified via CLI flags.