# Command-Line Interface (CLI) for Freebuff: Complete Usage Guide

> Explore the Freebuff command-line interface (CLI) with this comprehensive guide. Learn to leverage its interactive TUI or terminal-command broker for efficient development.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: how-to-guide
- Published: 2026-08-21

---

**Freebuff provides a dual-mode command-line interface located in the `cli/` directory, with [`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts) serving as the entry point that launches either an interactive TUI or terminal-command broker depending on whether you invoke it as `freebuff` or `codebuff`.**

The **command-line interface (CLI) for Freebuff** is a central component of the CodebuffAI/freebuff repository, providing both lightweight command execution and a full-featured terminal UI. Located under the `cli/` directory, this TypeScript-based tool uses the **commander** library for argument parsing in [`cli/src/cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/cli-args.ts) and supports multiple invocation modes depending on your workflow requirements.

## CLI Architecture and Entry Points

### The Entry Point ([`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts))

The CLI logic begins at [`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts), which determines whether to start the **interactive TUI** (Text User Interface) or run a **terminal-command broker**. This file imports the main application from [`cli/src/index.tsx`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/index.tsx) after making the mode determination based on how the binary was invoked.

### Dual Invocation Modes

Freebuff operates in two distinct modes:

- **`freebuff`**: A simplified command set for quick operations like login, version checks, and session management
- **`codebuff`**: The full-featured mode with advanced options including agent configuration, logging controls, and planning capabilities

## Command-Line Arguments and Options

### Simplified Mode (`freebuff`)

When invoked as **freebuff**, the CLI presents a limited but essential set of flags defined in [`cli/src/cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/cli-args.ts):

- `-v, --version`: Prints the current CLI version sourced from [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) or the `CODEBUFF_CLI_VERSION` environment variable
- `-h, --help`: Displays the help screen with available commands
- `--continue [conversation-id]`: Resumes a prior conversation; optionally accepts a specific conversation ID
- `--cwd <directory>`: Sets the working directory for the session (defaults to current directory)
- `[command]` (choices: `login`): Executes built-in commands; currently supports the `login` command for authentication

### Full-Featured Mode (`codebuff`)

When invoked as **codebuff**, additional options become available:

- `--agent <id>`: Specifies the agent ID to use for the session
- `--clear-logs`: Clears existing logs before starting
- `--lite`: Runs in lightweight mode with reduced features
- `--max`: Enables maximum capability mode
- `--plan`: Initiates planning mode for complex operations
- `prompt`: Accepts an initial prompt string directly

## Installation and Binary Configuration

The CLI binary is defined in [`cli/package.json`](https://github.com/CodebuffAI/freebuff/blob/main/cli/package.json) under the `"bin"` field as **`codebuff-tui`**. After installing dependencies with `bun install`, you can invoke the interface using:

```bash
codebuff-tui          # Launches the OpenTUI-based terminal UI

codebuff-tui --help   # Displays the UI help text

```

The package structure separates the CLI logic into the `cli/` directory while maintaining the release utilities in [`freebuff/cli/release.ts`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/release.ts).

## Practical Usage Examples

### Basic Freebuff Commands

```bash

# Show version information

freebuff -v

# Display help documentation

freebuff -h

# Authenticate with your Codebuff account

freebuff login

# Start CLI in a specific project directory

freebuff --cwd /path/to/project

# Resume the most recent session

freebuff --continue

# Resume a specific conversation by ID

freebuff --continue a1b2c3

```

### Full-Featured Codebuff Usage

```bash

# Run with specific agent and clear logs, passing an initial prompt

codebuff --agent my-agent-id --clear-logs "Explain this function"

```

### Running from Source

```bash

# Execute version command using the entry script directly

bun cli/src/entry.ts -v

```

## Advanced CLI Operations

### Programmatic Argument Parsing

You can import the argument parser for custom scripts:

```typescript
import { parseArgs } from './cli/src/cli-args';

const args = parseArgs({ argv: ['node', 'freebuff', '--cwd', '/my/project'] });
console.log(args);
// => { cwd: '/my/project', command: null, ... }

```

### Release Management ([`freebuff/cli/release.ts`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/release.ts))

The CLI includes a release script for version management:

```bash

# Bump version and start release workflow (patch level)

bun freebuff/cli/release.ts patch

```

This script handles version bumping and initiates the release workflow directly from the repository root.

## Summary

- The **entry point** resides at [`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts), which routes between TUI and command-broker modes
- **Argument parsing** occurs in [`cli/src/cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/cli-args.ts) using the commander library with typed `ParsedArgs` output
- Two **invocation modes** exist: `freebuff` (simplified) and `codebuff` (full-featured with advanced flags)
- The **binary name** is `codebuff-tui`, defined in [`cli/package.json`](https://github.com/CodebuffAI/freebuff/blob/main/cli/package.json)
- **Session persistence** is available via the `--continue` flag with optional conversation ID specification
- **Release operations** can be triggered via [`freebuff/cli/release.ts`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/release.ts) for version management

## Frequently Asked Questions

### How do I install the Freebuff CLI?

Install dependencies using `bun install` from the repository root, then invoke the binary as `codebuff-tui`. The executable is defined in [`cli/package.json`](https://github.com/CodebuffAI/freebuff/blob/main/cli/package.json) and provides access to both simplified (`freebuff`) and full-featured (`codebuff`) modes depending on how you call it.

### What is the difference between `freebuff` and `codebuff` commands?

The `freebuff` command provides a simplified interface with basic flags like `--version`, `--help`, `--continue`, and `--cwd`, plus the `login` command. The `codebuff` command unlocks the full feature set including `--agent`, `--clear-logs`, `--lite`, `--max`, and `--plan` flags, designed for complex development workflows.

### How do I resume a previous conversation in the CLI?

Use the `--continue` flag optionally followed by a conversation ID. Running `freebuff --continue` resumes the most recent session, while `freebuff --continue a1b2c3` restores a specific conversation. This functionality is handled by the argument parser in [`cli/src/cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/cli-args.ts) and processed by the entry point at [`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts).

### Where is the CLI entry point located in the source code?

The primary entry point is [`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts), which determines whether to launch the interactive TUI or the terminal-command broker. This file loads the main application from [`cli/src/index.tsx`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/index.tsx) and relies on [`cli/src/cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/cli-args.ts) for parsing command-line arguments using the commander library.