### Install Dependencies and Build Project

Source: https://github.com/acossta/captan/blob/main/CONTRIBUTING.md

Clone the repository, install project dependencies using Yarn, run tests to verify the setup, and build the project.

```bash
git clone https://github.com/YOUR_USERNAME/captan.git
cd captan

yarn install

yarn test

yarn build
```

--------------------------------

### Development Setup and Execution

Source: https://github.com/acossta/captan/blob/main/README.md

Clone the repository, install dependencies, build the project, and run the CLI in development mode.

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

```bash
yarn dev init --name "DemoCo"
```

--------------------------------

### Interactive Cap Table Initialization

Source: https://github.com/acossta/captan/blob/main/README.md

Use the wizard for a guided, step-by-step setup of your company's cap table.

```bash
# 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
```

--------------------------------

### Install Captan using npx

Source: https://github.com/acossta/captan/blob/main/README.md

Installs and runs Captan without a global installation using npx. Useful for quick checks.

```bash
npx captan@latest --help
```

--------------------------------

### Install Captan Globally

Source: https://github.com/acossta/captan/blob/main/README.md

Installs Captan globally using npm, making the 'captan' command available system-wide.

```bash
npm install -g captan
captan --help
```

--------------------------------

### Example CHANGELOG.md Section

Source: https://github.com/acossta/captan/blob/main/CLAUDE.md

Illustrates the format for updating the CHANGELOG.md file according to Keep a Changelog standards.

```markdown
## [0.2.3] - 2025-08-20

### Added
- Feature descriptions

### Fixed
- Bug fix descriptions

### Changed
- Changes to existing functionality
```

--------------------------------

### Initialize Cap Table

Source: https://github.com/acossta/captan/blob/main/README.md

Initializes a new cap table. Use --wizard for an interactive setup. Can set company name and authorized shares.

```bash
captan init [--wizard] [--name "Company"] [--authorized 10000000]
```

--------------------------------

### Format Validation Example Output

Source: https://github.com/acossta/captan/blob/main/README.md

Example output showing validation failures related to data formats like dates and emails.

```bash
$ 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
```

--------------------------------

### Display Captan Version

Source: https://github.com/acossta/captan/blob/main/README.md

Shows the currently installed version of Captan.

```bash
captan version
```

--------------------------------

### Check Captan Version

Source: https://github.com/acossta/captan/blob/main/README.md

Verify the installed version of Captan. This can be done directly or using npx.

```bash
captan --version
```

```bash
npx captan@latest --version
```

--------------------------------

### Business Rule Validation Example Output

Source: https://github.com/acossta/captan/blob/main/README.md

Example output demonstrating validation failures for business rules, such as invalid references or exceeding authorized shares.

```bash
$ 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
```

--------------------------------

### Example Test Case

Source: https://github.com/acossta/captan/blob/main/CONTRIBUTING.md

A sample test case written using Vitest, demonstrating how to import a service, instantiate it with a mock model, call a method, and assert the expected outcome.

```typescript
import { describe, it, expect } from 'vitest';
import { YourService } from './your-service.js';

describe('YourService', () => {
  it('should do something', () => {
    const service = new YourService(mockModel);
    const result = service.doSomething();
    expect(result).toBe(expectedValue);
  });
});
```

--------------------------------

### Check Captan Version

Source: https://github.com/acossta/captan/blob/main/README.md

Checks the currently installed global version of Captan.

```bash
captan --version
```

--------------------------------

### Update Option Grant Vesting Start Date

Source: https://github.com/acossta/captan/blob/main/README.md

Updates the vesting start date for an option grant.

```bash
captan grant update [id] [--vesting-start 2024-06-01]
```

--------------------------------

### Commit Message Format Example

Source: https://github.com/acossta/captan/blob/main/CONTRIBUTING.md

An example of a commit message following the conventional commits format, including a type (feat), a scope, a subject, and a body detailing the changes.

```git
feat: Add support for SAFE instruments

- Add SAFE as new security type
- Implement conversion calculations
- Update reporting to include SAFEs
```

--------------------------------

### Add a New Command to CLI

Source: https://github.com/acossta/captan/blob/main/CONTRIBUTING.md

Example of how to add a new command to the Captan CLI, including defining its description, options, and action logic. It demonstrates error handling and saving model changes.

```typescript
// In cli.ts
program
  .command('your-command')
  .description('Description of your command')
  .option('-o, --option <value>', 'option description')
  .action((opts) => {
    const model = load();
    const service = new YourService(model);
    
    try {
      // Your logic here
      save(model);
      console.log('✅ Success message');
    } catch (error: any) {
      console.error(`❌ ${error.message}`);
      process.exit(1);
    }
  });
```

--------------------------------

### Update Captan Globally

Source: https://github.com/acossta/captan/blob/main/README.md

Updates a globally installed Captan to the latest version using npm.

```bash
npm install -g captan@latest
```

--------------------------------

### Add and Manage SAFEs

Source: https://github.com/acossta/captan/blob/main/README.md

Use these commands to add new SAFEs, list outstanding SAFEs, and preview or execute SAFE conversions.

```bash
captan safe add --stakeholder sh_angel --amount 50000 --cap 5000000 --discount 20
captan safe add --stakeholder sh_vc --amount 150000 --cap 8000000
```

```bash
captan safe list
```

```bash
captan safe convert --pre-money 10000000 --pps 2.00 --dry-run
```

```bash
captan safe convert --pre-money 10000000 --pps 2.00
```

```bash
captan safe list
```

```bash
captan report ownership
```

--------------------------------

### Manage Multiple Security Classes

Source: https://github.com/acossta/captan/blob/main/README.md

Add new security classes like preferred stock and issue shares against them.

```bash
captan security add --kind PREFERRED --label "Series A" --authorized 3000000 --par 0.001
```

```bash
captan issuance add --security sc_xyz --stakeholder sh_investor --qty 2000000 --pps 2.00
```

--------------------------------

### Run Tests

Source: https://github.com/acossta/captan/blob/main/README.md

Execute the test suite and generate code coverage reports.

```bash
yarn test
yarn test:coverage
```

--------------------------------

### Display Help for a Command

Source: https://github.com/acossta/captan/blob/main/README.md

Shows help information for a specific Captan command.

```bash
captan help [command]
```

--------------------------------

### Run All Tests

Source: https://github.com/acossta/captan/blob/main/CONTRIBUTING.md

Commands for executing the test suite, including running all tests, tests in watch mode, tests with coverage, and specific test files.

```bash
yarn test

yarn test:watch

yarn test:coverage

yarn test src/model.test.ts
```

--------------------------------

### Project Structure Overview

Source: https://github.com/acossta/captan/blob/main/CONTRIBUTING.md

A hierarchical view of the Captan project's directory and file structure, highlighting key components like the CLI entry point, data models, services, and configuration files.

```bash
captan/
├── src/
│   ├── cli.ts                 # CLI entry point
│   ├── model.ts               # Data models and calculations
│   ├── store.ts               # File persistence
│   ├── branding.ts            # App constants
│   └── services/              # Business logic
│       ├── stakeholder-service.ts
│       ├── security-service.ts
│       ├── equity-service.ts
│       ├── reporting-service.ts
│       └── audit-service.ts
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md
```

--------------------------------

### List Security Classes

Source: https://github.com/acossta/captan/blob/main/README.md

Lists all defined security classes. Output can be formatted as JSON.

```bash
captan security list [--format json]
```

--------------------------------

### Create GitHub Release

Source: https://github.com/acossta/captan/blob/main/CLAUDE.md

Creates a GitHub release using the GitHub CLI, including release notes generated from a heredoc.

```bash
gh release create v0.2.3 --title "v0.2.3 - Brief Description" --notes "$(cat <<'EOF'
## What's Changed

### ✨ Features
- Feature 1
- Feature 2

### 🐛 Bug Fixes
- Fix 1

###  রক্ষণ Infrastructure
- Change 1

### 📚 Documentation
- Update 1

**Full Changelog**: https://github.com/acossta/captan/compare/v0.2.2...v0.2.3
EOF
)"
```

--------------------------------

### Manage SAFE Investments

Source: https://github.com/acossta/captan/blob/main/README.md

Commands for adding, listing, and converting SAFE (Simple Agreement for Future Equity) investments.

```bash
# 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
```

--------------------------------

### Simulate SAFE Conversion Scenarios

Source: https://github.com/acossta/captan/blob/main/README.md

Test different valuation scenarios for SAFE conversions using the --dry-run flag to compare pricing terms without making permanent changes.

```bash
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
```

--------------------------------

### Show Option Grant Details

Source: https://github.com/acossta/captan/blob/main/README.md

Displays details for a specific option grant by its ID.

```bash
captan grant show [id]
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/acossta/captan/blob/main/CONTRIBUTING.md

Commands for running the project in development mode, executing tests in watch mode, checking types, and running the full test suite.

```bash
yarn dev init --name "TestCo"

yarn test:watch

yarn validate:fix

yarn test:all
```

--------------------------------

### One-Minute Cap Table Flow

Source: https://github.com/acossta/captan/blob/main/README.md

A quick sequence of commands to initialize a cap table, grant options, view ownership, and export data.

```bash
# 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:alice@acme.com:5000000" \
  --founder "Bob Engineer:bob@acme.com: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
```

--------------------------------

### List Stakeholders

Source: https://github.com/acossta/captan/blob/main/README.md

Lists all stakeholders. Can format output as JSON.

```bash
captan stakeholder list [--format json]
```

--------------------------------

### Show SAFE Investment Details

Source: https://github.com/acossta/captan/blob/main/README.md

Displays details for a specific SAFE investment by its ID.

```bash
captan safe show [id]
```

--------------------------------

### Show Security Class Details

Source: https://github.com/acossta/captan/blob/main/README.md

Displays details for a specific security class by its ID.

```bash
captan security show [id]
```

--------------------------------

### List Option Grants

Source: https://github.com/acossta/captan/blob/main/README.md

Lists option grants, optionally filtered by stakeholder. Output can be JSON formatted.

```bash
captan grant list [--stakeholder id-or-email] [--format json]
```

--------------------------------

### Generate Ownership Report

Source: https://github.com/acossta/captan/blob/main/README.md

Generates an ownership report as of a specific date.

```bash
captan report ownership [--date 2024-01-01]
```

--------------------------------

### Show Stakeholder Details

Source: https://github.com/acossta/captan/blob/main/README.md

Displays details for a specific stakeholder identified by their ID or email.

```bash
captan stakeholder show [id-or-email]
```

--------------------------------

### Convert SAFE to Equity

Source: https://github.com/acossta/captan/blob/main/README.md

Converts a SAFE investment into equity, specifying pre-money valuation and price per share. Use --dry-run for simulation.

```bash
captan safe convert --pre-money 10000000 --pps 2.00 [--dry-run]
```

--------------------------------

### Add Custom Vesting Schedules for Grants

Source: https://github.com/acossta/captan/blob/main/README.md

Define custom vesting periods and cliff durations when adding new grants. Use --no-vesting for immediate vesting.

```bash
captan grant add --stakeholder sh_alice --qty 100000 --exercise 0.25 \
  --vesting-months 36 --cliff-months 6
```

```bash
captan grant add --stakeholder sh_bob --qty 50000 --exercise 0.10 --no-vesting
```

--------------------------------

### Generate Detailed Reports and Filter Logs

Source: https://github.com/acossta/captan/blob/main/README.md

Generate ownership reports in JSON format, filter audit logs by action, and retrieve detailed stakeholder reports.

```bash
captan report ownership --format json
```

```bash
captan log --action ISSUANCE_ADD --limit 10
```

```bash
captan report stakeholder sh_alice
```

--------------------------------

### Show Share Issuance Details

Source: https://github.com/acossta/captan/blob/main/README.md

Displays details for a specific share issuance by its ID.

```bash
captan issuance show [id]
```

--------------------------------

### Create Release Branch

Source: https://github.com/acossta/captan/blob/main/CLAUDE.md

Creates a new branch for the release from the main branch and sets the upstream.

```bash
git checkout main
git pull origin main
git checkout -b release/v0.2.3
# Set upstream immediately to avoid push issues
git push --set-upstream origin release/v0.2.3
```

--------------------------------

### Add a SAFE Investment

Source: https://github.com/acossta/captan/blob/main/README.md

Records a SAFE (Simple Agreement for Future Equity) investment. Can specify a valuation cap.

```bash
captan safe add --stakeholder <id-or-email> --amount 100000 [--cap 5000000]
```

--------------------------------

### TypeScript Class Naming Convention

Source: https://github.com/acossta/captan/blob/main/CONTRIBUTING.md

Demonstrates the preferred PascalCase convention for class names in TypeScript, contrasting it with an avoided snake_case style.

```typescript
// ✅ Good
export class StakeholderService {
  constructor(private model: FileModel) {}
  
  addStakeholder(name: string, type: 'person' | 'entity'): Stakeholder {
    // Implementation
  }
}

// ❌ Avoid
export class stakeholder_service {
  model: any;
  
  add(n, t) {
    // Implementation
  }
}
```

--------------------------------

### Update SAFE Investment Discount

Source: https://github.com/acossta/captan/blob/main/README.md

Updates the discount percentage for a SAFE investment.

```bash
captan safe update [id] [--discount 20]
```

--------------------------------

### Add a Security Class

Source: https://github.com/acossta/captan/blob/main/README.md

Adds a new class of security, like Common Stock. Can set an authorized share limit.

```bash
captan security add --kind COMMON --label "Common Stock" [--authorized 10000000]
```

--------------------------------

### List SAFE Investments

Source: https://github.com/acossta/captan/blob/main/README.md

Lists SAFE investments, optionally filtered by stakeholder. Output can be JSON formatted.

```bash
captan safe list [--stakeholder id-or-email] [--format json]
```

--------------------------------

### Export Cap Table to PDF

Source: https://github.com/acossta/captan/blob/main/README.md

Exports the cap table data to a PDF file. Defaults to 'captable.pdf'.

```bash
captan export pdf [--output captable.pdf]
```

--------------------------------

### List Share Issuances

Source: https://github.com/acossta/captan/blob/main/README.md

Lists share issuances, optionally filtered by stakeholder. Output can be JSON formatted.

```bash
captan issuance list [--stakeholder id-or-email] [--format json]
```

--------------------------------

### Generate Cap Table Summary Report

Source: https://github.com/acossta/captan/blob/main/README.md

Generates a summary report of the cap table. Output can be JSON formatted.

```bash
captan report summary [--format json]
```

--------------------------------

### Bump Version with Yarn

Source: https://github.com/acossta/captan/blob/main/CLAUDE.md

Bumps the package version using yarn commands based on semantic versioning. This automatically creates a git commit and tag.

```bash
# Choose based on semantic versioning:
yarn release:patch  # Bug fixes (0.2.2 -> 0.2.3)
yarn release:minor  # New features (0.2.3 -> 0.3.0)
yarn release:major  # Breaking changes (0.3.0 -> 1.0.0)
```

--------------------------------

### View Audit Log

Source: https://github.com/acossta/captan/blob/main/README.md

Displays the audit log, optionally filtered by action and limited by count.

```bash
captan log [--action ISSUANCE_ADD] [--limit 10]
```

--------------------------------

### Add a Stakeholder

Source: https://github.com/acossta/captan/blob/main/README.md

Adds a new stakeholder to the cap table. Use --entity PERSON for individuals.

```bash
captan stakeholder add --name "Alice" --email "alice@example.com" [--entity PERSON]
```

--------------------------------

### Add an Option Grant

Source: https://github.com/acossta/captan/blob/main/README.md

Grants stock options to a stakeholder with a specified quantity and exercise price.

```bash
captan grant add --stakeholder <id-or-email> --qty 100000 --exercise 0.10
```

--------------------------------

### Generate Stakeholder Report

Source: https://github.com/acossta/captan/blob/main/README.md

Generates a report for a specific stakeholder identified by ID or email.

```bash
captan report stakeholder [id-or-email]
```

--------------------------------

### Add a Share Issuance

Source: https://github.com/acossta/captan/blob/main/README.md

Records the issuance of shares to a stakeholder for a specific security class.

```bash
captan issuance add --stakeholder <id-or-email> --security <id> --qty 1000000
```

--------------------------------

### Generate Security Report

Source: https://github.com/acossta/captan/blob/main/README.md

Generates a report for a specific security class by its ID.

```bash
captan report security [id]
```

--------------------------------

### Generate Cap Table Schema

Source: https://github.com/acossta/captan/blob/main/README.md

Generates the JSON schema for the cap table file.

```bash
captan schema [--output captable.schema.json]
```

--------------------------------

### Throwing Descriptive Errors in TypeScript

Source: https://github.com/acossta/captan/blob/main/CONTRIBUTING.md

Illustrates how to throw informative errors in TypeScript when a condition is not met, such as a missing entity.

```typescript
if (!stakeholder) {
  throw new Error(`Stakeholder with ID "${id}" not found`);
}
```

--------------------------------

### Export Cap Table to JSON

Source: https://github.com/acossta/captan/blob/main/README.md

Exports the cap table data to a JSON file. Defaults to 'captable.json'.

```bash
captan export json [--output captable.json]
```

--------------------------------

### Export Cap Table to CSV

Source: https://github.com/acossta/captan/blob/main/README.md

Exports the cap table data to a CSV file. Defaults to 'captable.csv'.

```bash
captan export csv [--output captable.csv]
```

--------------------------------

### Update Stakeholder Information

Source: https://github.com/acossta/captan/blob/main/README.md

Updates an existing stakeholder's name or email.

```bash
captan stakeholder update [id-or-email] [--name "New Name"] [--email "new@example.com"]
```

--------------------------------

### Validate Cap Table

Source: https://github.com/acossta/captan/blob/main/README.md

Validates the cap table file. Use --extended for more thorough checks.

```bash
captan validate [--extended] [--file captable.json]
```

--------------------------------

### Captan Validation Commands

Source: https://github.com/acossta/captan/blob/main/README.md

Execute Captan's validation features, including basic format checks, extended business rule validation, and schema generation.

```bash
# 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
```

--------------------------------

### Update Share Issuance Quantity

Source: https://github.com/acossta/captan/blob/main/README.md

Updates the quantity of shares for an existing issuance.

```bash
captan issuance update [id] [--qty 2000000]
```

--------------------------------

### Update Security Class Authorization

Source: https://github.com/acossta/captan/blob/main/README.md

Updates the authorized share count for a security class.

```bash
captan security update [id] [--authorized 20000000]
```

--------------------------------

### Delete a SAFE Investment

Source: https://github.com/acossta/captan/blob/main/README.md

Deletes a SAFE investment record. Requires --force to confirm deletion of investment.

```bash
captan safe delete [id] [--force]
```

--------------------------------

### Deprecate NPM Version

Source: https://github.com/acossta/captan/blob/main/CLAUDE.md

Deprecates a specific version of a package on npm.

```bash
npm deprecate captan@0.2.3 "Contains critical bug"
```

--------------------------------

### Delete a Security Class

Source: https://github.com/acossta/captan/blob/main/README.md

Deletes a security class. Requires --force if shares have been issued.

```bash
captan security delete [id] [--force]
```

--------------------------------

### Delete Local Tag

Source: https://github.com/acossta/captan/blob/main/CLAUDE.md

Deletes a local git tag.

```bash
git tag -d v0.2.3
```

--------------------------------

### Delete a Share Issuance

Source: https://github.com/acossta/captan/blob/main/README.md

Deletes a share issuance record. Requires --force to confirm deletion of ownership.

```bash
captan issuance delete [id] [--force]
```

--------------------------------

### Clean Up Local and Remote Branches

Source: https://github.com/acossta/captan/blob/main/CLAUDE.md

Deletes the local and remote release branch after the merge to main.

```bash
git checkout main
git pull origin main
git branch -d release/v0.2.3  # Delete local branch
git push origin --delete release/v0.2.3  # Delete remote branch
```

--------------------------------

### Delete an Option Grant

Source: https://github.com/acossta/captan/blob/main/README.md

Deletes an option grant. Requires --force if any options have vested.

```bash
captan grant delete [id] [--force]
```

--------------------------------

### Delete a Stakeholder

Source: https://github.com/acossta/captan/blob/main/README.md

Deletes a stakeholder. Requires --force if the stakeholder has equity holdings.

```bash
captan stakeholder delete [id-or-email] [--force]
```

--------------------------------

### Delete Remote Tag

Source: https://github.com/acossta/captan/blob/main/CLAUDE.md

Deletes a remote git tag.

```bash
git push origin --delete v0.2.3
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.