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 ski...

Security Scan

The skill's instructions expect installing and running a third‑party CLI (npx corp) and performing high‑impact tasks (formation, auto‑signing, payroll), but the skill metadata omits required binaries/install details and doesn't declare any credentials — these mismatches are concerning and should be verified before installing or running anything.

Purpose & Capability

The SKILL.md describes a full CLI for corporate formation, governance, payroll, document generation and auto‑signing. That purpose reasonably requires a Node/npx runtime and an install of @thecorporation/cli (and apparently a Rust binary shipped by that package). However the skill metadata declares no required binaries and no install spec. The metadata and runtime instructions are inconsistent: a consumer would reasonably expect 'node'/'npx' to be listed as required and the package install to be declared.

Instruction Scope

Instructions tell the agent to run 'npx corp setup', run servers (npx corp serve), store data under ~/.corp/data, and to 'activate' entities which auto‑signs formation documents. Those are legitimate for a corp management CLI, but they are high‑impact operations (legal document signing, payroll). The instructions do not require explicit confirmation workflows in the SKILL.md — e.g., the automated 'activate' auto‑sign behavior is scope‑creep for an assistant unless the user explicitly consents at time of action. The skill also references cloud magic‑link auth (external endpoints) and configuring api_url, which will transmit data to external services.

Install Mechanism

The SKILL.md informs the agent to use an npm package (@thecorporation/cli) via npx — an install from the public npm registry. Installing arbitrary CLI packages via npx is a moderate‑risk action (remote published code/binaries may execute locally). The registry metadata omitted an install spec, but the instructions do include an install block — this discrepancy is notable. There are no checksums or pinned versions in the instructions; the skill asks implicitly to fetch code at runtime.

Credentials

The skill metadata lists no required environment variables or credentials, yet the SKILL.md describes a cloud mode (magic link auth) and operations that commonly require credentials (payroll, document filing). The lack of declared credential requirements is disproportionate to the sensitive operations described. Additionally, the skill stores data locally (~/.corp/data) which may contain sensitive corporate and personal data; SKILL.md does not discuss encryption or access control.

Persistence & Privilege

The skill does not request always:true and is user‑invocable. It does instruct running a persistent local HTTP server (npx corp serve) and changing agent config (npx corp config set api_url ...), which are normal developer actions but have side effects (open local ports, change config). These behaviors are plausible for the stated purpose but warrant caution (run in an isolated environment if uncertain).

What to consider before installing

This skill instructs the agent to install and run a third‑party CLI (npx @thecorporation/cli) that can create legal entities, auto‑sign documents, manage payroll, and run a local server. Before installing or running anything: 1) Confirm the npm package identity and review its source code (the SKILL.md links to a GitHub repo); prefer pinned versions and checksums. 2) Ensure Node/npx are available — the skill metadata should have listed these; ask the publisher to declare required binaries and versions. 3) Don’t allow auto‑signing or payroll actions without explicit, per‑action user confirmation — these are legally and financially sensitive. 4) Prefer local/self‑hosted mode for testing, inspect ~/.corp/data for sensitive content, and consider running the CLI in an isolated VM or container. 5) If you plan to use cloud mode, verify the cloud service operator and magic‑link flow and avoid sending real credentials or personal data until you’ve validated the service. If the publisher cannot explain the metadata/install discrepancies or provide a reproducible audit path (source repo, commit/tag, checksums), treat the skill as potentially unsafe.

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

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)

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

Cloud mode

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

Advanced: Local server mode

For development with a persistent HTTP server:

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

Verify Context

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:

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:

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

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

1. Create a governance body

   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

   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

   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

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

   Repeat --present-seat for each seat present.

7. Vote on agenda item

   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

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

9. Finalize item

   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:

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:

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:

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:

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

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

   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

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

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

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

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

Payroll

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

Documents

Generate a contract

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

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

PDF Preview

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

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:

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

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

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)

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

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

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:

npx corp schema --json

For help on any specific command:

npx corp <command> --help