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:

FormatExampleDescriptionFull UUID763dde4d-ca62-4e20-90ba-662c462d4b09Canonical IDShort ID763dde4dFirst segment of UUID@last``@lastMost recently created resource of that typeName/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=jane@acme.com,role=director,officer_title=ceo,is_incorporator=true,address=123 Main St|Dover|DE|19901" \
  --member "name=John Doe,email=john@acme.com,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 jane@acme.com --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 jane@acme.com --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#

FlagDescriptionScope--jsonJSON output (machine-readable)Nearly all commands--dry-runPreview request without executingMost write operations--entity-id <ref>Scope to an entityEntity-scoped commands--forceAllow security-sensitive updatesconfig 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