@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 company use "Acme Inc"          # if you have more than one
captable-ai documents upload ./docs/*.pdf
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

| Command | Description | |---------|-------------| | login / logout | Authenticate / clear stored credentials | | auth status | Show the current session | | company list\|use\|current\|create\|delete | Manage and select the active company | | documents upload\|list\|download\|delete | Manage source documents | | documents trigger-extraction\|cancel-extraction\|restart-extraction\|reprocess | Control the OCF extraction pipeline | | documents processing-status\|classification-types\|classification-update | Inspect document status / classification | | objects list\|get\|update\|patch\|revert\|versions\|delete | Work with extracted OCF objects | | schemas list\|get | Browse the OCF object-type registry | | commit | Commit drafts to the cap table — --all or --objects id1,id2 (--dry-run to preview) | | summary | Full cap table snapshot | | export / register | Export the cap table (Excel) / shareholder register | | pro-forma run | Model financing, convertible, warrant, and option-pool scenarios | | retrigger-validation | Re-queue a stalled validator | | jobs list\|get\|prune | Track async operations | | profile save\|use\|list\|get\|delete | Named configuration profiles | | logs | View agent/extraction logs | | feedback | Report CLI friction to the maintainers | | commands | Machine-readable list of all commands and flags |

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

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:

| Code | Meaning | |------|---------| | 0 | Success | | 2 | Usage error (bad/unknown flag, missing argument) | | 3 | Auth required / session expired | | 4 | Not found | | 5 | Conflict (version conflict, nothing to commit) | | 6 | Validation error | | 7 | Server error (5xx) | | 8 | Network error |

Environment variables

| Variable | Purpose | |----------|---------| | CAPTABLE_AI_STAGE / STAGE | Target environment: production (default), staging, dev, local | | CAPTABLE_AI_API_URL | Override the API base URL | | CAPTABLE_AI_AUTH_URL | Override the login page URL | | CAPTABLE_AI_PORTAL_ID | Override the active company for a single invocation | | CAPTABLE_AI_FEEDBACK_URL | Endpoint for feedback send |

License

MIT © Fairmint, Inc.