@fairmint/captable-ai

Agent-native command-line interface for Captable AI. Manage companies, upload documents, run OCF (Open Cap Format) extraction, review and edit extracted objects, and commit cap tables — all from your terminal or an AI agent.

Built for both humans and AI agents: every command supports --json for structured, parseable output, uses a stable exit-code taxonomy, and rejects unknown flags with helpful errors.

Installation

npm install -g @fairmint/captable-ai

This exposes two binaries: captable-ai and the short alias cai. Requires Node.js >= 20.

Authentication

captable-ai login

Opens your browser to authenticate. After approving, click "Finish in browser" or paste the login code back into the terminal. Credentials are stored in ~/.captable-ai/. Use captable-ai logout to clear them and captable-ai auth status to inspect the session.

Quickstart

captable-ai login
captable-ai onboarding status
captable-ai onboarding setup ...            # only when you have no workspace
captable-ai company use "Acme Inc"           # if you have more than one
captable-ai import start
captable-ai documents upload ./docs/*.pdf
captable-ai import status <session-id>
captable-ai documents trigger-extraction    # once all docs are CLASSIFIED
captable-ai documents list                  # poll until PROCESSED
captable-ai commit --dry-run                 # preview
captable-ai commit --all                     # commit all drafts (or --objects id1,id2)
captable-ai summary

Uploading documents — the optimal flow

CaptableAI builds your cap table by reading your legal documents. The pipeline is automated, but a few habits make extraction faster and more accurate:

1. Upload everything first. Add all of your cap table documents up front, in one batch where possible — incorporation docs, SAFEs, stock and option agreements, board consents. Supported: PDF, DOCX, XLSX, DOC, and images, up to 50 MB per file via the CLI. captable-ai documents upload ./docs/*.pdf
2. Wait for classification. Each document is OCR'd and classified (type + effective date). Don't trigger extraction until every document shows CLASSIFIED. captable-ai documents list
3. Check the classification dates. The effective date set during classification determines processing order. Fix a wrong date before triggering extraction: captable-ai documents classification-update
4. Trigger extraction once. Extraction does not start automatically for CLI uploads — run it a single time after all documents are classified. captable-ai documents trigger-extraction
5. Let the FIFO queue run. Documents are extracted one at a time, in ascending order of their classification date (earliest first), so later events build on earlier ones. Expect a few minutes per document.
6. Validation runs automatically. Once the last document finishes extraction, a company-wide validator runs across all objects to repair cross-document issues — no action needed.
7. Review, then commit. When all documents reach PROCESSED, review and commit. captable-ai objects list --status draft → captable-ai commit --dry-run → captable-ai commit --all (commit requires --all or --objects id1,id2,...).

Be patient — and when to retry:

• Extraction and validation are asynchronous. Poll captable-ai documents list (or captable-ai documents processing-status) rather than re-triggering — duplicate triggers just slow things down.
• Per-document extraction and the validator are only considered stuck after roughly 15 minutes of no progress. Wait out that window before assuming a problem.
• Retry commands are a last resort, used only after the wait window: documents reprocess (a FAILED doc), documents cancel-extraction / documents restart-extraction (a genuinely stuck doc), or retrigger-validation (a stalled validator).

Commands

Run captable-ai <command> --help for full usage, or captable-ai commands --json for the authoritative machine-readable list.

Signed agreements

documents list holds what the extraction pipeline ingested. Signed agreements are listed separately, whether or not they were ingested:

captable-ai agreements list                      # investments and grants, newest signed first
captable-ai agreements list --type grant --json
captable-ai agreements download grant:<awardId>  # one-hour download link

• Investments — the signed file of a SAFE (Send One SAFE, Community SAFE), custom document, or legacy investment, once signed, whether or not payment is marked.
• Grants — Send One Grants both parties signed. The download is the agreement, supporting documents, and both signature certificates. The grantee's tax form and 83(b) election are never included; download those from Studio.

Legacy grant agreements imported through the extraction pipeline stay under documents list / documents download.

Instrument registers

captable-ai export with no register is the full legal cap table: a multi-sheet Excel workbook returned as a one-hour download link. Four registers export one instrument family, one row per security:

captable-ai export stock                                   # Excel download link
captable-ai export grants --include-pending                # options, RSUs, other awards
captable-ai export warrants --json                         # rows as a JSON array
captable-ai export convertibles --type SAFE --csv          # SAFEs only, CSV on stdout
captable-ai export convertibles --type NOTE --json --output notes.json

Every register carries the holder fields (name, email, address, country, state) and the economics of that family. Grants lead with the grant date; convertibles put the signature date, execution date, and status right after the holder. Without a format flag the result is one Excel sheet returned as a download link. --csv prints RFC-4180 CSV whose header row is the JSON keys; --json prints the rows as a JSON array. Pass one or neither. --output <path> writes the CSV or JSON body to a file and, for these commands only, does not imply --json.

By default a register lists the committed cap table only. --include-pending adds what is not committed yet: draft OCF objects, plus investment, equity_grant, and equity_award (Send One Grant) rows that have no OCF transaction. A row that already has an OCF object appears once. Registers are read-only and never commit drafts. You must be an owner or admin of the active company.

Structured output

Pass --json to any command for machine-readable output. Data goes to stdout, errors go to stderr, and the process exits with a typed code:

Environment variables

License

MIT © Fairmint, Inc.