prepcli

getting started

installation

prepcli is a global CLI tool. Install it once and use it across all your projects.

$curl -fsSL https://prepcli.in/install.sh | bash# recommended

Requires Node.js 18 or later. The script checks your Node version, installs prepcli globally, and prints next steps. Or install directly via npm:

$npm install -g @prepcli/prepcli

After installation, prepcli --version should print the current version.

authentication

Authentication uses email OTP — no passwords. Run the login command and enter your email. A 6-digit code is sent to your inbox. Enter the code to authenticate.

$prepcli auth login
Email: you@example.com
Check your inbox for a 6-digit code.
Code: 482193
Logged in as you@example.com

The auth token is stored in ~/.prepcli/config.json with mode 0600. It is never committed, never synced, never included in any project file. Run prepcli auth logout to invalidate the session and delete the local token.

initialize a project

Run prepcli init inside your project directory. It scans your codebase (package.json, lock files, config files), detects the stack, creates a .prepclirc file, and pushes an initial project context to the cloud.

$cd my-project
$prepcli init
Scanning codebase...
Detected: Next.js 16, TypeScript 5, tRPC, Prisma, TailwindCSS, pnpm
Pushing context to cloud...
Done. .prepclirc created (safe to commit).
Git hook installed at .git/hooks/pre-push

.prepclirc contains only a project_id UUID and the API URL — no secrets. It is safe to commit. Every team member who clones the repo connects to the same project context automatically.

install workflow files

Run prepcli install to copy the six workflow files to your AI tools. It auto-detects Claude Code, Cursor, Windsurf, and Antigravity based on config files present in your environment.

$prepcli install
Detected: Claude Code, Cursor
Installed 6 workflow files to ~/.claude/commands/
Installed 6 workflow files to .cursor/rules/
$prepcli install --tool claude-code# install to one tool
$prepcli install --tool cursor,windsurf
$prepcli install --tool antigravity

using slash commands

Once prepcli install completes, the six workflow files are registered as native slash commands in your AI tool. You invoke them directly in the chat or terminal interface — no extra terminal, no flags, no copy-paste.

# available in Claude Code, Cursor, Windsurf, and Antigravity
/debuginvestigate a bug — project context loaded before the first question
/planplan a feature or change before writing any code
/prepprime the AI with full context before a long task
/refactorrefactor code with project constraints enforced
/reviewreview a diff or PR with decision history in scope
/writegenerate new code with full context and active constraints

In Claude Code, type the command in the chat panel or the in-terminal prompt. In Cursor, open the chat panel (⌘L) and type the slash command. In Windsurf, use the Cascade chat panel. In Antigravity, type it in the chat interface. The tool routes it to the installed workflow file, which silently loads your project context before the session starts.

# Claude Code terminal or chat
/debug there's a timezone bug in the calendar
# Cursor — Cmd+L → chat panel
/plan add dark mode support to the settings page
# Windsurf — Cascade chat
/refactor the auth module is getting too large
# Antigravity — chat panel
/review

Each session is tracked automatically. At git push, prepcli surfaces the accumulated turns and asks for a one-line summary before saving the decision to your project history.

commands reference

prepcli auth

$prepcli auth login# send OTP, store token
$prepcli auth logout# invalidate session, delete token
$prepcli auth status# show logged-in user and token expiry

prepcli init

Scans the current directory, detects the stack, creates .prepclirc, pushes initial context to cloud, creates the decision history branch, and installs the pre-push git hook.

$prepcli init# private project (default)
$prepcli init --org acme# link to an organization
$prepcli init --public# public project, community opt-in

Re-running prepcli init is safe. It never recreates or overwrites the decision history. It only updates the context snapshot and re-installs hooks if missing.

prepcli context

Fetch and display the current project context stored in the cloud.

$prepcli context# print full context as JSON
$prepcli context --preview# show what gets injected at session start
$prepcli context edit# open context editor

prepcli install / update

$prepcli install# install to all detected AI tools
$prepcli install --tool claude-code
$prepcli install --tool cursor,windsurf
$prepcli update# show diff before overwriting workflow files

prepcli session

Called by AI workflow files at the end of each task. Writes one session turn to the local .prepcli-session file. No network call. No auth required. Works offline.

prepcli session add \
--workflow=debug \
--what="identified date-fns as root cause" \
--why="UTC+5:30 half-hour offsets fail silently"

At git push, the pre-push hook reads .prepcli-session, shows the accumulated turns, and asks for one final summary sentence before saving. Pressing Enter skips recording — the push is never blocked.

prepcli log

Browse decisions from your project's history.

$prepcli log# last 10 decisions
$prepcli log --last 30d# last 30 days
$prepcli log --workflow debug# filter by workflow type
$prepcli log --file src/auth.ts# decisions touching this file
$prepcli log --commit a4f2c1d# linked to a specific commit

prepcli record

Manually save a decision. Use this for decisions not tied to an AI session — architectural discoveries, dependency choices, security decisions.

$prepcli record# interactive mode
prepcli record \
--workflow=refactor \
--what="migrated from date-fns to custom UTC handler" \
--why="no half-hour offset support" \
--ruled-out="dayjs, moment.js"

how it works

context injection

Every workflow file begins with a silent context fetch. Before the AI asks the user a single question, it loads your project context from the cloud — stack, constraints, recent decisions, hard limits, and open questions.

The AI carries this context silently and operates as if it already knows the project. It does not announce what it read or summarize it back — it just uses it.

# what gets loaded at session start
stack: your detected framework, language, tooling
active_constraints: things the AI must respect — absolute
recent_decisions: what was decided recently and why
hard_limits: project boundaries that cannot be crossed
open_questions: unresolved items — flagged if relevant

the decision history

Every AI work session is recorded as a structured decision — what was done, why, what was ruled out, what constraints were active. Records are linked to the commits they produced, travel with every clone of the repo, and are readable without a prepcli account.

$prepcli log
May 24 · debug · 3 turns · commit a4f2c1d
rebuilt calendar — dropped date-fns for custom UTC handler
Why: date-fns has no support for UTC+5:30 half-hour offsets
Tried: dayjs (same problem), moment.js (too heavy)

decision records format

Each record is a structured Markdown file with YAML frontmatter. The frontmatter links it to the commit. The body contains the full narrative.

---
id: dec-a4f2c1d
commit: a4f2c1d
date: 2025-05-24T11:30:00Z
workflow: debug
files_changed: [src/calendar.tsx, src/utils/date.ts]
---
## Summary
Rebuilt calendar with custom timezone handling — dropped date-fns
## Why This Approach
date-fns had no support for UTC+5:30 half-hour offsets
## What Was Tried and Ruled Out
- date-fns — no half-hour offset support
- dayjs — same problem with spacetime plugin
- moment.js — too heavy (67KB), same issue
## Constraints Active at Time of Decision
- No new npm dependencies
- Must support UTC+5:30

self-hosting

prepcli uses Supabase as its cloud backend. The schema is open — enterprise users can self-host on their own Supabase instance (or raw PostgreSQL with pgvector) with no code changes.

supabase setup

Create a Supabase project, enable the pgvector extension, and run the schema migrations. Then set SUPABASE_URL and SUPABASE_ANON_KEY in the prepcli environment.

-- enable pgvector
create extension if not exists vector;
-- core tables
users, projects, project_members
project_context, prompt_sessions, delta_records

environment variables

SUPABASE_URLyour Supabase project URL
SUPABASE_ANON_KEYpublic anon key — safe to expose in CLI

row level security

All tables have Row Level Security enabled. Users can only read and write data for projects they are members of. This isolation is enforced at the database level — bypassing it at the application layer is not possible.

-- members can only read their project's sessions
create policy "member_read_sessions" on prompt_sessions
for select using (
exists (
select 1 from project_members
where project_id = prompt_sessions.project_id
and user_id = auth.uid()
)
);