Repofence CLI

0.2.2 · active · verified Wed Apr 22

Repofence is a command-line interface (CLI) tool designed to streamline the process of preparing software repositories for AI agents. It enables developers to generate structured specifications and AI-specific rules directly from their codebase, ensuring AI tools operate within defined boundaries. The current stable version is 0.2.2, indicating it's an early-stage but actively developed tool. Its key differentiators include local-first operation for codebase scanning (`repofence reverse`), explicit support for various AI assistants like Cursor and Claude, and a focus on creating documentation artifacts (`spec/*.md`) that guide both human developers and AI agents. It aims to prevent AI agents from "guessing" and instead work with clear, auto-generated boundaries.

Common errors

```
Error: Not Authenticated. Please run 'repofence auth --web' to get a license.
```
cause Attempting to run `repofence init` or other commands before successfully authenticating with a Repofence license.

fix Run `repofence auth --web` in your terminal and follow the instructions to obtain and save your authentication token.
```
command not found: repofence
```
cause The `repofence` CLI was not installed globally, or the global npm bin directory is not in your system's PATH.

fix Ensure you install the package globally using `npm install -g repofence`. If the problem persists, verify your PATH environment variable includes the npm global bin directory.
```
Node.js version mismatch. Repofence requires Node.js >=18.0.0.
```
cause The system's installed Node.js version is older than the minimum requirement specified in the package's engines field.

fix Upgrade your Node.js installation to version 18.0.0 or higher. Consider using `nvm` (Node Version Manager) for easy switching between Node.js versions.

Warnings

breaking The `--force` flag on `repofence init` and `repofence reverse` can overwrite existing spec files, potentially losing customized documentation. Use with caution, especially in established projects.
Fix: Review `--dry-run` output before using `--force` to understand changes. Backup important `spec/*.md` files.
gotcha Most `repofence` commands (e.g., `init`) require prior authentication with a valid license token. Attempting to use them without `repofence auth` will result in errors.
Fix: Run `repofence auth --web` in your terminal and follow the instructions to obtain and save your authentication token.
gotcha For brownfield (existing) projects, it is strongly recommended to run `repofence reverse` immediately after `repofence init`. This populates the generated spec files with information derived from your existing codebase, ensuring the specs accurately reflect the current state before any AI-driven modifications.
Fix: Execute `repofence reverse` as an early step in the workflow for brownfield projects.
gotcha Repofence integrates with specific AI assistants like Cursor and Claude. The `repofence init [ide]` command installs assistant-specific files and configurations which are crucial for the AI integration to function correctly. Ensure you specify the correct IDE for your workflow.
Fix: Specify `repofence init cursor` or `repofence init claude` to install the appropriate assets for your AI assistant. Verify installation paths like `~/.cursor/commands/`.

Install

npm install repofence npm
yarn add repofence yarn
pnpm add repofence pnpm

Imports

repofence command
wrong:
```
import { repofence } from 'repofence'
```
correct:
```
npm install -g repofence
```
This package is primarily a global CLI tool. Functionality is accessed via the `repofence` command in the terminal after global installation. Direct programmatic import as a library is not the intended primary use, despite shipping TypeScript types.
Repofence configuration types
wrong:
```
import { RepofenceConfig } from 'repofence'
```
correct:
```
import type { RepofenceConfig } from 'repofence'
```
While the package ships TypeScript types, its main interaction is via the CLI. If any configuration interfaces (e.g., for internal scripting or advanced integration) are exposed, they would typically be imported as types. The exact names may vary as the API is not publicly documented.
Command-specific options types
wrong:
```
import { InitOptions } from 'repofence'
```
correct:
```
import type { InitOptions } from 'repofence'
```
For specific CLI commands like `init` or `reverse`, corresponding TypeScript interfaces for their options (e.g., `InitOptions`, `ReverseOptions`) might be exported for advanced use cases or internal tooling. Developers should consult the type declarations if programmatic interaction is attempted beyond the CLI.

Quickstart

Demonstrates global installation and the core workflow: authentication, project initialization, and auto-population of specifications.

npm install -g repofence

# 1. Purchase a license and get your token
repofence auth --web

# 2. Initialize spec files + install assistant assets (Cursor by default)
repofence init

# 3. Auto-populate specs from your codebase
repofence reverse

view raw JSON →