Captan

Command your ownership.

Open Source Cap Table Management CLI

✨ Overview

Captan is a lightweight, hackable CLI tool for managing startup cap tables. Keep ownership records simple and transparent with a single JSON file (captable.json).

🪶 Zero database required — just git & JSON
📊 Real cap table math: outstanding vs fully diluted
⏳ Simple vesting schedules with cliffs
📜 Audit log for every action
📤 Export to CSV/JSON for investors & lawyers

📖 Usage

Captan uses a resource-oriented command structure.

Stakeholder Commands

captan stakeholder add --name "Alice" --email "[email protected]" [--entity PERSON]
captan stakeholder list [--format json]
captan stakeholder show [id-or-email]
captan stakeholder update [id-or-email] [--name "New Name"] [--email "[email protected]"]
captan stakeholder delete [id-or-email] [--force]  # --force required if stakeholder has holdings

Security Class Commands

captan security add --kind COMMON --label "Common Stock" [--authorized 10000000]
captan security list [--format json]
captan security show [id]
captan security update [id] [--authorized 20000000]
captan security delete [id] [--force]  # --force required if shares have been issued

Issuance Commands

captan issuance add --stakeholder <id-or-email> --security <id> --qty 1000000
captan issuance list [--stakeholder id-or-email] [--format json]
captan issuance show [id]
captan issuance update [id] [--qty 2000000]
captan issuance delete [id] [--force]  # --force required to delete share ownership

Option Grant Commands

captan grant add --stakeholder <id-or-email> --qty 100000 --exercise 0.10
captan grant list [--stakeholder id-or-email] [--format json]
captan grant show [id]
captan grant update [id] [--vesting-start 2024-06-01]
captan grant delete [id] [--force]  # --force required if options are vested

SAFE Commands

captan safe add --stakeholder <id-or-email> --amount 100000 [--cap 5000000]
captan safe list [--stakeholder id-or-email] [--format json]
captan safe show [id]
captan safe update [id] [--discount 20]
captan safe delete [id] [--force]  # --force required to delete investments
captan safe convert --pre-money 10000000 --pps 2.00 [--dry-run]

Report Commands

captan report summary [--format json]
captan report ownership [--date 2024-01-01]
captan report stakeholder [id-or-email]
captan report security [id]

Export Commands

captan export csv [--output captable.csv]
captan export json [--output captable.json]
captan export pdf [--output captable.pdf]

System Commands

captan init [--wizard] [--name "Company"] [--authorized 10000000]
captan validate [--extended] [--file captable.json]
captan schema [--output captable.schema.json]
captan log [--action ISSUANCE_ADD] [--limit 10]
captan version
captan help [command]

⚠️ Destructive Operations

Some commands require the --force flag to prevent accidental data loss:

stakeholder delete - Requires --force if the stakeholder has any equity holdings
security delete - Requires --force if any shares have been issued from this class
issuance delete - Requires --force to confirm deletion of share ownership records
grant delete - Requires --force if any options have vested
safe delete - Requires --force to confirm deletion of investment records

These safeguards help prevent accidental deletion of important ownership data.

🚀 QuickStart

Install

Use npx (no install):

npx captan@latest --help

Or install globally:

npm install -g captan
captan --help

Requires Node.js 20+

Updating

If you have captan installed globally:

# Check current version
captan --version

# Update to latest version
npm install -g captan@latest

# Verify update
captan --version

If you're using npx, it always fetches the latest by default:

npx captan@latest --version

💡 Note: npm update -g captan doesn't work for global packages. You must use npm install -g captan@latest to update.

One-minute flow

# 1. Initialize with founders and pool (C-Corp with 20% pool)
captan init \
  --name "Acme, Inc." \
  --date "2024-01-15" \
  --authorized 10000000 \
  --founder "Alice Founder:[email protected]:5000000" \
  --founder "Bob Engineer:[email protected]:3000000" \
  --pool-pct 20

# 2. Grant options from the pool
captan grant add --stakeholder sh_bob --qty 200000 --exercise 0.10

# 3. View your cap table
captan report ownership

# 4. Export to CSV
captan export csv > captable.csv

💡 IDE Support: Captan automatically creates captable.schema.json for autocomplete and validation in VS Code and other editors that support JSON Schema.

Interactive Setup

# Use the wizard for guided setup
captan init --wizard

# Prompts you through:
# - Company name & type (C-Corp, S-Corp, LLC)
# - State of incorporation
# - Authorized shares/units
# - Option pool configuration
# - Founder equity splits

💰 SAFE Support

# Add a SAFE investment
captan safe add \
  --stakeholder sh_alice \
  --amount 100000 \
  --cap 5000000 \
  --discount 20 \
  --note "YC SAFE"

# List all SAFEs
captan safe list

# Convert SAFEs at Series A (permanent - SAFEs become shares)
captan safe convert \
  --pre-money 10000000 \
  --new-money 3000000 \
  --pps 2.00

📊 Sample Output

📊 Captan — Cap Table (as of 2025-08-16)
Name                      Outstanding    %
Alice Founder                  5000000   96.15%
Bob Eng                          80000    1.54%

Totals
Issued equity:       5000000
Vested options:      80000
Outstanding total:   5080000
FD issued:           5000000
FD grants:           200000
FD pool remaining:   1800000
Fully diluted total: 7000000

🧩 Features

Stakeholder management
Security classes (common, preferred, option pools)
Share issuances
Option grants & vesting schedules
SAFE investments (with cap, discount, conversion simulation)
Cap table reports (outstanding & FD, with SAFEs)
Export CSV/JSON
Audit history (the "ship's log")

📋 JSON Schema & Validation

Captan provides enterprise-grade JSON schema validation with comprehensive error checking and IDE integration.

✨ Key Features

🔍 Format Validation: Automatic validation of dates, emails, UUIDs, currency codes
🧠 Business Rules: Cross-entity reference checking, authorized share limits, duplicate detection
💡 IDE Support: Real-time autocomplete and validation in VS Code and other editors
⚠️ Smart Warnings: Non-critical issues flagged separately from errors
📊 Enterprise Ready: Handles complex cap tables with comprehensive validation

🚀 Usage

# Basic validation - checks format and structure
captan validate

# Extended validation - includes business rules and cross-references
captan validate --extended

# Generate schema file for IDE integration
captan schema --output captable.schema.json

# Validate a specific file
captan validate --file my-captable.json

💻 IDE Integration

When you run captan init, a captable.schema.json file is automatically created in your directory. This enables:

Autocomplete: IntelliSense for all captable properties
Real-time validation: Immediate error highlighting
Documentation: Hover hints with field descriptions
Type safety: Prevents common data entry errors

🎯 Validation Examples

Format validation:

$ captan validate
❌ Validation failed for captable.json:
  • company.formationDate: Date must be in YYYY-MM-DD format
  • stakeholders[0].email: Invalid email format
  • company.currency: String must contain exactly 3 characters

Business rule validation:

$ captan validate --extended
❌ Validation failed for captable.json:
  • issuances[0].stakeholderId: Invalid stakeholder reference 'sh_nonexistent'
  • securityClasses[0]: Issued shares (1,100,000) exceed authorized (1,000,000)

⚠️ Warnings:
  • stakeholders[2]: Stakeholder has no equity, options, or SAFEs
  • safes[0]: SAFE has neither cap nor discount - conversion may be problematic

🔧 What Gets Validated

Category	Basic Mode	Extended Mode
Format	✅ Dates, emails, UUIDs	✅ All format validation
Structure	✅ Required fields, types	✅ All structural validation
References	❌	✅ Stakeholder/security class refs
Business Rules	❌	✅ Share limits, duplicate IDs
Consistency	❌	✅ Date ordering, pool usage
Warnings	❌	✅ Orphaned entities, missing terms

Concepts

Outstanding vs Fully Diluted

Outstanding = issued equity (common + preferred) + vested options
Fully diluted = issued equity + all granted options + remaining option pool

Vesting

Options vest monthly with cliff periods:

Standard: 4 years (48 months) with 1-year cliff
Options don't count as outstanding until vested
Full grant counts toward fully diluted from day one

SAFE Conversions

SAFEs (Simple Agreement for Future Equity) are placeholder investments that convert to shares at a priced round.

How SAFEs Work:

Investment: Investor provides capital via SAFE (not equity yet)
Terms: SAFEs can have a valuation cap and/or discount
Conversion: At next priced round, SAFEs convert to shares
Price: Converts at the LOWEST of:
- Round price: The actual price per share
- Cap price: Valuation cap ÷ pre-money shares
- Discount price: Round price × (1 - discount%)
Permanent: After conversion, SAFEs disappear - replaced by share issuances

Pre-money vs Post-money SAFEs:

Pre-money: Cap applies to company value BEFORE the SAFE money
Post-money: Cap includes the SAFE investment itself (YC standard)

Example SAFE Lifecycle:

# 1. Add SAFEs during seed stage
captan safe add --stakeholder sh_angel --amount 50000 --cap 5000000 --discount 20
captan safe add --stakeholder sh_vc --amount 150000 --cap 8000000

# 2. Check outstanding SAFEs
captan safe list
# Shows: $200k in SAFEs outstanding

# 3. PREVIEW conversion (no changes made) - NEW!
captan safe convert --pre-money 10000000 --pps 2.00 --dry-run

# Output:
# 🔄 SAFE Conversion Preview
# 
# Angel Investor:
#   Investment: $50,000
#   Shares: 31,250 at $1.60/share (discount)
#   New ownership: 1.2%
#
# VC Fund:
#   Investment: $150,000  
#   Shares: 75,000 at $2.00/share (cap)
#   New ownership: 2.8%
#
# Total new shares: 106,250
# Post-money shares: 2,606,250
# Dilution to existing: 4.1%

# 4. EXECUTE conversion (permanent)
captan safe convert --pre-money 10000000 --pps 2.00

# Conversion calculation for sh_angel:
# - Round price: $2.00
# - Cap price: $5M ÷ 2.5M shares = $2.00  
# - Discount price: $2.00 × 0.8 = $1.60 ← BEST PRICE
# - Converts: $50k ÷ $1.60 = 31,250 shares

# 5. SAFEs are now gone
captan safe list
# Shows: No SAFEs outstanding

captan report ownership
# Shows: sh_angel now owns shares, not a SAFE

Simulating Different Conversion Scenarios:

# Test different valuations without committing
captan safe convert --pre-money 8000000 --pps 1.60 --dry-run
captan safe convert --pre-money 12000000 --pps 2.40 --dry-run
captan safe convert --pre-money 15000000 --pps 3.00 --dry-run

# Compare which pricing terms apply at different valuations
# Higher valuations may trigger cap prices
# Lower valuations may make discount prices more favorable

Data Storage

All data lives in captable.json in your current directory:

Version control friendly (commit it!)
Human-readable JSON format
Complete audit trail included
Works great alongside company docs in a repo
JSON Schema support: captable.schema.json provides IDE autocomplete and validation
Built-in validation: Run captan validate to catch errors before they cause problems
Schema versioning: Forward/backward compatibility with automatic migration guidance

Advanced Usage

Custom Vesting Schedules

# 3-year vest, 6-month cliff
captan grant add --stakeholder sh_alice --qty 100000 --exercise 0.25 \
  --vesting-months 36 --cliff-months 6

# Immediate vesting (no schedule)
captan grant add --stakeholder sh_bob --qty 50000 --exercise 0.10 --no-vesting

Multiple Security Classes

# Add Series A Preferred
captan security add --kind PREFERRED --label "Series A" --authorized 3000000 --par 0.001

# Issue preferred shares
captan issuance add --security sc_xyz --stakeholder sh_investor --qty 2000000 --pps 2.00

Detailed Reports

# JSON format for cap table (for integrations)
captan report ownership --format json

# Filter audit log
captan log --action ISSUANCE_ADD --limit 10

# Stakeholder detail report
captan report stakeholder sh_alice

Architecture

Captan uses a service-oriented architecture:

Services: Business logic (stakeholder, security, equity, reporting, audit)
Model: Data types and calculations (Zod validated)
Store: File persistence layer
CLI: Thin command interface

🛠️ Development

git clone https://github.com/<your-org>/captan
cd captan
yarn install
yarn build
node dist/cli.js --help

Run in dev mode:

yarn dev init --name "DemoCo"

Run tests:

yarn test
yarn test:coverage

🤝 Contributing

Pull requests are welcome! Please open an issue first for major changes. For development setup, see CONTRIBUTING.md (coming soon).

📜 License

⚠️ Disclaimer

Captan is not legal advice. Always verify calculations and consult professionals before sending cap tables to investors or making equity decisions.

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
.github/workflows		.github/workflows
.husky		.husky
src		src
.gitignore		.gitignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
logo.png		logo.png
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.setup.ts		vitest.setup.ts
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

Captan

Open Source Cap Table Management CLI

✨ Overview

📖 Usage

Stakeholder Commands

Security Class Commands

Issuance Commands

Option Grant Commands

SAFE Commands

Report Commands

Export Commands

System Commands

⚠️ Destructive Operations

🚀 QuickStart

Install

Updating

One-minute flow

Interactive Setup

💰 SAFE Support

📊 Sample Output

🧩 Features

📋 JSON Schema & Validation

✨ Key Features

🚀 Usage

💻 IDE Integration

🎯 Validation Examples

🔧 What Gets Validated

Concepts

Outstanding vs Fully Diluted

Vesting

SAFE Conversions

How SAFEs Work:

Pre-money vs Post-money SAFEs:

Example SAFE Lifecycle:

Simulating Different Conversion Scenarios:

Data Storage

Advanced Usage

Custom Vesting Schedules

Multiple Security Classes

Detailed Reports

Architecture

🛠️ Development

🤝 Contributing

📜 License

⚠️ Disclaimer

🌐 Links

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages