TheCorporation.ai Form and Operate

How to use the npx corp CLI to manage corporate entities, governance, cap tables, finance, agents, and compliance for TheCorporation platform. Use this skill whenever the user mentions npx corp, TheCorporation, corporate formation, entity governance, cap table management, equity issuance, 409A valuations, board meetings, written consent, SAFE instruments, corporate agents, work items, or any task involving programmatic corporate governance. Also use when the user wants to form an LLC or C-Corp, manage board seats, issue stock options, run payroll, generate legal documents, or automate corporate compliance workflows.

npx corp CLI Skill

The npx corp CLI is the command-line interface for TheCorporation platform — a corporate governance system built by agents, for agents. It manages the full lifecycle of business entities: formation, governance, cap tables, finance, documents, tax, compliance, agents, and work items.

Quick Start

Setup

bash

npx corp setup

Choose a hosting mode:

• Local (your machine) — no server needed. Data stored in ~/.corp/data. Each command invokes the Rust binary directly (~6ms).
• TheCorporation cloud — hosted service, authenticates via magic link.
• Self-hosted server — point to your own API server URL.

Local mode (recommended for development)

bash

npx corp setup              # choose "Local (your machine)"
npx corp status             # verify — all local, no network

Cloud mode

bash

npx corp setup              # choose "TheCorporation cloud"
# Follow the magic link auth flow

Advanced: Local server mode

For development with a persistent HTTP server:

bash

npx corp serve --port 8020
npx corp config set api_url http://localhost:8020 --force

Verify Context

bash

npx corp context

Shows active workspace, user, entity, and hosting mode.

Reference Resolution

The CLI supports flexible reference formats across all commands:

Format	Example	Description
Full UUID	763dde4d-ca62-4e20-90ba-662c462d4b09	Canonical ID
Short ID	763dde4d	First segment of UUID
@last	@last	Most recently created resource of that type
Name/Handle	"Acme Corp"	Unique name match

Use npx corp resolve <kind> <ref> to test resolution. Use npx corp find <kind> <query> to list matches.

Entity Formation

One-Shot Formation (Recommended for Agents)

Form an entity in a single command using key=value member syntax:

bash

npx corp form \
  --type c_corp \
  --name "Acme Inc" \
  --jurisdiction US-DE \
  --member "name=Jane Doe,email=[e-mail],role=director,officer_title=ceo,is_incorporator=true,address=123 Main St|Dover|DE|19901" \
  --member "name=John Doe,email=[e-mail],role=director,officer_title=cto,address=456 Oak Ave|Dover|DE|19901" \
  --json

One-shot flags:

• --type <type> — Entity type (see below)
• --name <name> — Legal name of the entity
• --jurisdiction <jurisdiction> — e.g. US-DE, US-WY
• --member <spec> — Founder (repeatable); key=value format with keys: name, email, role (director|officer|manager|member|chair), officer_title (ceo|cfo|cto|coo|secretary|treasurer|president|vp|other), is_incorporator (true|false), address (street|city|state|zip), pct (ownership %), shares (shares purchased)
• --address <address> — Company address as street,city,state,zip
• --fiscal-year-end <date> — Fiscal year end (MM-DD, default "12-31")
• --s-corp — Elect S-Corp status
• --transfer-restrictions — Enable transfer restrictions
• --rofr — Enable right of first refusal

Important: Member addresses use pipe | as separator (street|city|state|zip), NOT commas.

Staged Formation

For more control, use the staged flow:

1. Create — npx corp form create --type c_corp --name "Acme Inc" --jurisdiction US-DE --json
2. Add Founders — npx corp form add-founder @last --name "Jane Doe" --email [e-mail] --role director --pct 100 --officer-title ceo --incorporator --address "123 Main St,Dover,DE,19901" --json
3. Finalize — npx corp form finalize @last --board-size 1 --company-address "123 Main St,Dover,DE,19901" --json
4. Activate — npx corp form activate @last --json

The activate step transitions from documents_generated to active status by auto-signing formation documents.

Staged add-founder flags:

• --name (required), --email (required), --role (required: director|officer|manager|member|chair), --pct (required: ownership %)
• --officer-title <title> (choices: ceo, cfo, cto, coo, secretary, treasurer, president, vp, other)
• --incorporator (boolean flag — mark as sole incorporator)
• --address <address> (as street,city,state,zip)

Staged finalize flags:

• --board-size <n>, --authorized-shares <n>, --par-value <value>
• --company-address, --incorporator-name, --incorporator-address
• --principal-name (LLC manager name)

Entity Types

c_corp, llc, lp, llp, gp, sole_prop, cooperative, nonprofit

Setting Active Entity

Most commands require an active entity context:

bash

npx corp config set active_entity_id <entity-ref>

Governance

Governance operates through bodies (e.g., Board of Directors), seats, meetings, and resolutions.

Full Meeting Lifecycle

text

create-body → add-seat → convene (with --agenda) → notice → open (--present-seat) → vote → resolve → finalize-item → adjourn

1. Create a governance body

   bash

   npx corp governance create-body --name "Board of Directors" --body-type board_of_directors --json
   

   Body types: board_of_directors, llc_member_vote

2. Add seats — <body-ref> is a positional argument

   bash

   npx corp governance add-seat @last --holder <contact-ref> --role member --json
   

   Roles: chair, member, officer, observer

3. Convene a meeting — --type and --body are required

   bash

   npx corp governance convene --body @last --type board_meeting --title "Board Meeting Q1" --date 2026-04-01 --agenda "Approve equity grant" --agenda "Review financials" --json
   

   Meeting types: board_meeting, shareholder_meeting, member_meeting, written_consent

   Agenda items are added via repeatable --agenda flags on convene. There is no separate agenda-items add command.

4. List agenda items — npx corp governance agenda-items <meeting-ref> --json

5. Send notice — npx corp governance notice <meeting-ref> --json

6. Open meeting with present seats

   bash

   npx corp governance open <meeting-ref> --present-seat <seat-ref> --json
   

   Repeat --present-seat for each seat present.

7. Vote on agenda item

   bash

   npx corp governance vote <meeting-ref> <item-ref> --voter <contact-ref> --vote for --json
   

   Vote values: for, against, abstain, recusal

8. Compute resolution — requires both <meeting-ref> and <item-ref> as positional args

   bash

   npx corp governance resolve <meeting-ref> <item-ref> --text "RESOLVED: The board approves the equity grant" --json
   

9. Finalize item

   bash

   npx corp governance finalize-item <meeting-ref> <item-ref> --status voted --json
   

   Status choices: discussed, voted, tabled, withdrawn

10. Adjourn — npx corp governance adjourn <meeting-ref> --json

Written Consent (Alternative to Meetings)

For board approvals without a formal meeting:

bash

npx corp governance written-consent --body <body-ref> --title "Approve Equity Grant" --description "Approve 10000 shares to Jane Doe" --json

Written consent produces a meeting_id and resolution that can be used for downstream operations like equity issuance. List the agenda items and vote to complete:

bash

npx corp governance agenda-items @last
npx corp governance vote @last <item-ref> --voter <contact-ref> --vote for --json

Cap Table

Instruments

Create equity instruments before issuing shares:

bash

npx corp cap-table create-instrument --kind common_equity --symbol COMMON --authorized-units 10000000 --issue-price-cents 1 --json

Instrument kinds: common_equity, preferred_equity, membership_unit, option_grant, safe

Flags:

• --kind <kind> (required) — instrument kind
• --symbol <symbol> (required) — e.g. COMMON, SERIES-A, OPTION-PLAN
• --authorized-units <n> — total authorized shares/units
• --issue-price-cents <n> — issue price in cents
• --issuer-legal-entity-id <ref> — auto-resolved if omitted
• --terms-json <json> — JSON object of additional terms

Issuing Equity

C-Corps require board approval (a resolution) before issuing equity:

bash

npx corp cap-table issue-equity --grant-type common --shares 100000 --recipient "Jane Doe" --meeting-id <meeting-ref> --resolution-id <resolution-ref> --json

Flags:

• --grant-type <type> (required) — common, preferred, membership_unit, stock_option, iso, nso, rsa
• --shares <n> (required) — number of shares
• --recipient <name> (required) — recipient name (not an ID)
• --email <email> — recipient email (auto-creates contact if needed)
• --instrument-id <ref> — instrument reference (auto-resolved by grant type if omitted)
• --meeting-id <ref> — board meeting reference (required for board-governed entities)
• --resolution-id <ref> — board resolution reference (required for board-governed entities)

SAFEs

bash

npx corp cap-table issue-safe --investor "Jane Investor" --amount 5000000 --valuation-cap 1000000000 --json

Important: --amount and --valuation-cap are in cents (e.g., 5000000 = $50,000).

Flags:

• --investor <name> (required) — investor name
• --amount <n> (required) — principal amount in cents
• --valuation-cap <n> (required) — valuation cap in cents
• --safe-type <type> — SAFE type (default: post_money)
• --meeting-id <ref> — board meeting reference
• --resolution-id <ref> — board resolution reference

409A Valuations

Three-step process:

1. Create valuation

   bash

   npx corp cap-table create-valuation --type four_oh_nine_a --date 2026-03-15 --methodology market --enterprise-value 120000000 --json
   

   Types: four_oh_nine_a, fair_market_value Methodologies: income, market, asset, backsolve, hybrid

2. Submit for approval — npx corp cap-table submit-valuation <valuation-ref> --json

3. Approve (after board resolution) — npx corp cap-table approve-valuation <valuation-ref> --resolution-id <resolution-ref> --json

Then check: npx corp cap-table 409a --json

Transfers

bash

npx corp cap-table transfer --from <contact-ref> --to <contact-ref> --shares 1000 --share-class-id <ref> --governing-doc-type bylaws --transferee-rights full_member --json

Distributions

bash

npx corp cap-table distribute --amount 100000 --type dividend --description "Q1 distribution" --json

Finance

Key subcommands: invoices, invoice, payroll-runs, payroll, payments, pay, bank-accounts, open-account, classifications, classify-contractor, reconciliations, reconcile, distributions.

Monetary amounts are in cents (e.g., --amount 500000 = $5,000).

Payments

bash

npx corp finance pay --amount 500000 --recipient "Jane Doe" --method ach --json

Note: Payments require an active bank account. Use npx corp finance open-account to create one (created in pending_review state).

Invoices

bash

npx corp finance invoice --customer "Client Co" --amount 1000000 --due-date 2026-04-01 --json

Payroll

bash

npx corp finance payroll --period-start 2026-03-01 --period-end 2026-03-15 --json

Documents

Generate a contract

bash

npx corp documents generate --template employment_offer --counterparty "Jane Doe" --param department=Engineering --param equity_grant_type=iso --param base_salary=150000 --json

Flags:

• --template <type> (required) — consulting_agreement, employment_offer, contractor_agreement, nda, custom
• --counterparty <name> (required) — counterparty name
• --effective-date <date> — ISO 8601 date (defaults to today)
• --base-salary <amount> — for employment_offer template
• --param <key=value> — additional template parameter (repeatable)

Signing

bash

npx corp documents signing-link <document-ref>
npx corp documents sign <document-ref> --json
npx corp documents sign-all --json

PDF Preview

bash

npx corp documents preview-pdf --definition-id bylaws

Known issue: preview-pdf fails in process:// local transport mode. Use cloud or HTTP server mode for PDF previews.

Templates: bylaws, operating_agreement, certificate_of_incorporation, articles_of_organization, employment_offer, nda, ip_assignment, etc.

Contacts

bash

npx corp contacts --json                                    # list all
npx corp contacts add --name "Jane Doe" --email [e-mail] --category founder --json
npx corp contacts edit <contact-ref> --category board_member --json
npx corp contacts show <contact-ref> --json

Categories: employee, contractor, board_member, investor, law_firm, valuation_firm, accounting_firm, officer, founder, member, other

Agents

Agents are autonomous actors that can claim work items and interact with the system:

bash

npx corp agents create --name "Ops Agent" --prompt "You manage corporate operations" --json
npx corp agents skill <agent-ref> --name "gov-watch" --description "Monitor governance deadlines" --json
npx corp agents message <agent-ref> --body "Check upcoming deadlines" --json
npx corp agents pause <agent-ref>
npx corp agents resume <agent-ref>
npx corp agents delete <agent-ref>

agents create flags:

• --name <name> (required) — agent display name
• --prompt <prompt> (required) — system prompt for the agent
• --model <model> — LLM model to use

Note: Agents are workspace-scoped, not entity-scoped. No --entity-id needed.

Agent payloads can be size-sensitive — keep skill descriptions and message bodies concise to avoid 500 errors. Use --body-file or --instructions-file for large content.

Work Items

bash

npx corp work-items create --entity-id <ref> --title "File annual report" --category compliance --description "File with DE SOS" --deadline 2026-06-01 --created-by agent --json
npx corp work-items claim <work-item-ref> --by "Ops Agent" --json
npx corp work-items complete <work-item-ref> --by "Ops Agent" --result "Filed successfully" --json
npx corp work-items release <work-item-ref>
npx corp work-items cancel <work-item-ref>

Note: --by is required for both claim and complete. Alias: --claimer for claim, --completed-by for complete.

Tax

bash

npx corp tax filings --json
npx corp tax file --type franchise_tax --year 2026 --json
npx corp tax deadlines --json
npx corp tax deadline --type annual_report --due-date 2026-06-01 --description "Delaware annual report" --json

Key Flags

Flag	Description	Scope
--json	JSON output (machine-readable)	Nearly all commands
--dry-run	Preview request without executing	Most write operations
--entity-id <ref>	Scope to an entity	Entity-scoped commands
--force	Allow security-sensitive updates	config set for api_key

Important Gotchas

1. C-Corp equity requires board approval — You must have a resolution_id from a governance vote or written consent before issuing equity on a C-Corp. LLCs do not have this requirement.

2. active_entity_id must be set — Most entity-scoped commands require either --entity-id or a configured active_entity_id.

3. Dollar sign in descriptions — $ characters in command arguments may be shell-interpolated. In descriptions like "$50K SAFE", the $50K can become 0K. Avoid $ or escape it properly.

4. SAFE instrument is NOT needed for issue-safe — Unlike issue-equity, the issue-safe command does not require a pre-existing instrument. It creates the SAFE directly.

5. Agent payload size — Large payloads to agents skill or agents message can cause 500 errors. Keep payloads short, or use --body-file/--instructions-file.

6. Formation finalize requires complete data — The staged flow requires --board-size and --company-address on finalize for C-Corps. Missing fields cause validation errors.

7. demo command — Use npx corp demo --name "Acme" --minimal for a reliable quick seed. Full scenarios (startup, llc, restaurant) may hit validation edge cases depending on version.

8. Monetary values are in cents — All financial amounts (--amount, --valuation-cap, --enterprise-value, --issue-price-cents, --price-per-share-cents) are in cents. 500000 = $5,000.

9. Role values — Member/seat roles are director, officer, manager, member, chair — NOT founder. Use founder as a contact category instead.

10. Body type values — Governance body types are board_of_directors, llc_member_vote — NOT board.

11. Address formats — One-shot --member addresses use pipe separator: street|city|state|zip. Staged --address and --company-address use comma separator: street,city,state,zip.

12. finance activate-account — Bank accounts are created in pending_review state. Use npx corp finance activate-account <account-ref> to activate before submitting payments.

13. Formation auto-creates board — Forming a C-Corp automatically creates a Board of Directors governance body. You don't need to create-body separately after formation.

14. LLC requires pct — LLC members require pct (ownership percentage). C-Corp members can use either pct or shares.

Workflow Patterns for Agents

Pattern: Form Entity + Issue Equity (C-Corp)

text

form (one-shot with --type c_corp) → config set active_entity_id @last → written-consent (approve equity) → cap-table issue-equity --grant-type common --shares <n> --recipient <name> --meeting-id <consent-meeting> --resolution-id <consent-resolution>

Note: Formation auto-creates a board, so skip create-body + add-seat if using one-shot formation.

Pattern: 409A Valuation Approval

text

cap-table create-valuation --type four_oh_nine_a --date <date> --methodology <method> → submit-valuation <valuation-ref> → governance written-consent (approve 409A) → approve-valuation <valuation-ref> --resolution-id <consent-resolution> → cap-table 409a

Pattern: Agent Task Loop

text

agents create --name <name> --prompt <prompt> → agents skill <agent-ref> --name <skill> --description <desc> → work-items create → work-items claim <ref> --by <agent-name> → work-items complete <ref> --by <agent-name> → agents message <agent-ref> --body "status report"

Further Reference

For the complete command catalog with all options, run:

bash

npx corp schema --json

For help on any specific command:

bash

npx corp <command> --help