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

Freebuff provides a dual-mode command-line interface located in the cli/ directory, with 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 and supports multiple invocation modes depending on your workflow requirements.

CLI Architecture and Entry Points

The Entry Point (cli/src/entry.ts)

The CLI logic begins at 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 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:

• -v, --version: Prints the current CLI version sourced from 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 under the "bin" field as codebuff-tui. After installing dependencies with bun install, you can invoke the interface using:

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.

Practical Usage Examples

Basic Freebuff Commands

# 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

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

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

Running from Source

# 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:

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)

The CLI includes a release script for version management:

# 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, which routes between TUI and command-broker modes
• Argument parsing occurs in 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
• Session persistence is available via the --continue flag with optional conversation ID specification
• Release operations can be triggered via 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 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 and processed by the entry point at cli/src/entry.ts.

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

The primary entry point is 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 and relies on cli/src/cli-args.ts for parsing command-line arguments using the commander library.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}