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 to test resolution. Use npx corp find 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=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 — Entity type (see below)
--name — Legal name of the entity
--jurisdiction — e.g. US-DE, US-WY
--member — 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
— Company address as street,city,state,zip
--fiscal-year-end — 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:

Create — npx corp form create --type c_corp --name "Acme Inc" --jurisdiction US-DE --json
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
Finalize — npx corp form finalize @last --board-size 1 --company-address "123 Main St,Dover,DE,19901" --json
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 </code> (choices: ceo, cfo, cto, coo, secretary, treasurer, president, vp, other)</li><li><code>--incorporator</code> (boolean flag — mark as sole incorporator)</li><li><code>--address <address></code> (as <code>street,city,state,zip</code>)</li></ul><p><strong>Staged <code>finalize</code> flags:</strong></p><ul><li><code>--board-size <n></code>, <code>--authorized-shares <n></code>, <code>--par-value <value></code></li><li><code>--company-address</code>, <code>--incorporator-name</code>, <code>--incorporator-address</code></li><li><code>--principal-name</code> (LLC manager name)</li></ul><h3>Entity Types</h3><p><code>c_corp</code>, <code>llc</code>, <code>lp</code>, <code>llp</code>, <code>gp</code>, <code>sole_prop</code>, <code>cooperative</code>, <code>nonprofit</code></p><h3>Setting Active Entity</h3><p>Most commands require an active entity context:</p><pre><code>npx corp config set active_entity_id <entity-ref> </code></pre><h2>Governance</h2><p>Governance operates through bodies (e.g., Board of Directors), seats, meetings, and resolutions.</p><h3>Full Meeting Lifecycle</h3><pre><code>create-body → add-seat → convene (with --agenda) → notice → open (--present-seat) → vote → resolve → finalize-item → adjourn </code></pre><ol><li><strong>Create a governance body</strong></li></ol><p> ```bash</p><p> npx corp governance create-body --name "Board of Directors" --body-type board_of_directors --json</p><p> ```</p><p> Body types: <code>board_of_directors</code>, <code>llc_member_vote</code></p><ol><li><strong>Add seats</strong> — <code><body-ref></code> is a positional argument</li></ol><p> ```bash</p><p> npx corp governance add-seat @last --holder <contact-ref> --role member --json</p><p> ```</p><p> Roles: <code>chair</code>, <code>member</code>, <code>officer</code>, <code>observer</code></p><ol><li><strong>Convene a meeting</strong> — <code>--type</code> and <code>--body</code> are required</li></ol><p> ```bash</p><p> 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</p><p> ```</p><p> Meeting types: <code>board_meeting</code>, <code>shareholder_meeting</code>, <code>member_meeting</code>, <code>written_consent</code></p><p> Agenda items are added via repeatable <code>--agenda</code> flags on <code>convene</code>. There is no separate <code>agenda-items add</code> command.</p><ol><li><strong>List agenda items</strong> — <code>npx corp governance agenda-items <meeting-ref> --json</code></li></ol><ol><li><strong>Send notice</strong> — <code>npx corp governance notice <meeting-ref> --json</code></li></ol><ol><li><strong>Open meeting with present seats</strong></li></ol><p> ```bash</p><p> npx corp governance open <meeting-ref> --present-seat <seat-ref> --json</p><p> ```</p><p> Repeat <code>--present-seat</code> for each seat present.</p><ol><li><strong>Vote on agenda item</strong></li></ol><p> ```bash</p><p> npx corp governance vote <meeting-ref> <item-ref> --voter <contact-ref> --vote for --json</p><p> ```</p><p> Vote values: <code>for</code>, <code>against</code>, <code>abstain</code>, <code>recusal</code></p><ol><li><strong>Compute resolution</strong> — requires both <code><meeting-ref></code> and <code><item-ref></code> as positional args</li></ol><p> ```bash</p><p> npx corp governance resolve <meeting-ref> <item-ref> --text "RESOLVED: The board approves the equity grant" --json</p><p> ```</p><ol><li><strong>Finalize item</strong></li></ol><p> ```bash</p><p> npx corp governance finalize-item <meeting-ref> <item-ref> --status voted --json</p><p> ```</p><p> Status choices: <code>discussed</code>, <code>voted</code>, <code>tabled</code>, <code>withdrawn</code></p><ol><li><strong>Adjourn</strong> — <code>npx corp governance adjourn <meeting-ref> --json</code></li></ol><h3>Written Consent (Alternative to Meetings)</h3><p>For board approvals without a formal meeting:</p><pre><code>npx corp governance written-consent --body <body-ref> --title "Approve Equity Grant" --description "Approve 10000 shares to Jane Doe" --json </code></pre><p>Written consent produces a <code>meeting_id</code> and resolution that can be used for downstream operations like equity issuance. List the agenda items and vote to complete:</p><pre><code>npx corp governance agenda-items @last npx corp governance vote @last <item-ref> --voter <contact-ref> --vote for --json </code></pre><h2>Cap Table</h2><h3>Instruments</h3><p>Create equity instruments before issuing shares:</p><pre><code>npx corp cap-table create-instrument --kind common_equity --symbol COMMON --authorized-units 10000000 --issue-price-cents 1 --json </code></pre><p><strong>Instrument kinds:</strong> <code>common_equity</code>, <code>preferred_equity</code>, <code>membership_unit</code>, <code>option_grant</code>, <code>safe</code></p><p><strong>Flags:</strong></p><ul><li><code>--kind <kind></code> (required) — instrument kind</li><li><code>--symbol <symbol></code> (required) — e.g. COMMON, SERIES-A, OPTION-PLAN</li><li><code>--authorized-units <n></code> — total authorized shares/units</li><li><code>--issue-price-cents <n></code> — issue price in cents</li><li><code>--issuer-legal-entity-id <ref></code> — auto-resolved if omitted</li><li><code>--terms-json <json></code> — JSON object of additional terms</li></ul><h3>Issuing Equity</h3><p>C-Corps require board approval (a resolution) before issuing equity:</p><pre><code>npx corp cap-table issue-equity --grant-type common --shares 100000 --recipient "Jane Doe" --meeting-id <meeting-ref> --resolution-id <resolution-ref> --json </code></pre><p><strong>Flags:</strong></p><ul><li><code>--grant-type <type></code> (required) — <code>common</code>, <code>preferred</code>, <code>membership_unit</code>, <code>stock_option</code>, <code>iso</code>, <code>nso</code>, <code>rsa</code></li><li><code>--shares <n></code> (required) — number of shares</li><li><code>--recipient <name></code> (required) — recipient name (not an ID)</li><li><code>--email <email></code> — recipient email (auto-creates contact if needed)</li><li><code>--instrument-id <ref></code> — instrument reference (auto-resolved by grant type if omitted)</li><li><code>--meeting-id <ref></code> — board meeting reference (required for board-governed entities)</li><li><code>--resolution-id <ref></code> — board resolution reference (required for board-governed entities)</li></ul><h3>SAFEs</h3><pre><code>npx corp cap-table issue-safe --investor "Jane Investor" --amount 5000000 --valuation-cap 1000000000 --json </code></pre><p><strong>Important:</strong> <code>--amount</code> and <code>--valuation-cap</code> are in <strong>cents</strong> (e.g., <code>5000000</code> = $50,000).</p><p><strong>Flags:</strong></p><ul><li><code>--investor <name></code> (required) — investor name</li><li><code>--amount <n></code> (required) — principal amount in cents</li><li><code>--valuation-cap <n></code> (required) — valuation cap in cents</li><li><code>--safe-type <type></code> — SAFE type (default: <code>post_money</code>)</li><li><code>--meeting-id <ref></code> — board meeting reference</li><li><code>--resolution-id <ref></code> — board resolution reference</li></ul><h3>409A Valuations</h3><p>Three-step process:</p><ol><li><strong>Create valuation</strong></li></ol><p> ```bash</p><p> npx corp cap-table create-valuation --type four_oh_nine_a --date 2026-03-15 --methodology market --enterprise-value 120000000 --json</p><p> ```</p><p> Types: <code>four_oh_nine_a</code>, <code>fair_market_value</code></p><p> Methodologies: <code>income</code>, <code>market</code>, <code>asset</code>, <code>backsolve</code>, <code>hybrid</code></p><ol><li><strong>Submit for approval</strong> — <code>npx corp cap-table submit-valuation <valuation-ref> --json</code></li></ol><ol><li><strong>Approve</strong> (after board resolution) — <code>npx corp cap-table approve-valuation <valuation-ref> --resolution-id <resolution-ref> --json</code></li></ol><p>Then check: <code>npx corp cap-table 409a --json</code></p><h3>Transfers</h3><pre><code>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 </code></pre><h3>Distributions</h3><pre><code>npx corp cap-table distribute --amount 100000 --type dividend --description "Q1 distribution" --json </code></pre><h2>Finance</h2><p>Key subcommands: <code>invoices</code>, <code>invoice</code>, <code>payroll-runs</code>, <code>payroll</code>, <code>payments</code>, <code>pay</code>, <code>bank-accounts</code>, <code>open-account</code>, <code>classifications</code>, <code>classify-contractor</code>, <code>reconciliations</code>, <code>reconcile</code>, <code>distributions</code>.</p><p>Monetary amounts are in <strong>cents</strong> (e.g., <code>--amount 500000</code> = $5,000).</p><h3>Payments</h3><pre><code>npx corp finance pay --amount 500000 --recipient "Jane Doe" --method ach --json </code></pre><p>Note: Payments require an active bank account. Use <code>npx corp finance open-account</code> to create one (created in <code>pending_review</code> state).</p><h3>Invoices</h3><pre><code>npx corp finance invoice --customer "Client Co" --amount 1000000 --due-date 2026-04-01 --json </code></pre><h3>Payroll</h3><pre><code>npx corp finance payroll --period-start 2026-03-01 --period-end 2026-03-15 --json </code></pre><h2>Documents</h2><h3>Generate a contract</h3><pre><code>npx corp documents generate --template employment_offer --counterparty "Jane Doe" --param department=Engineering --param equity_grant_type=iso --param base_salary=150000 --json </code></pre><p><strong>Flags:</strong></p><ul><li><code>--template <type></code> (required) — <code>consulting_agreement</code>, <code>employment_offer</code>, <code>contractor_agreement</code>, <code>nda</code>, <code>custom</code></li><li><code>--counterparty <name></code> (required) — counterparty name</li><li><code>--effective-date <date></code> — ISO 8601 date (defaults to today)</li><li><code>--base-salary <amount></code> — for employment_offer template</li><li><code>--param <key=value></code> — additional template parameter (repeatable)</li></ul><h3>Signing</h3><pre><code>npx corp documents signing-link <document-ref> npx corp documents sign <document-ref> --json npx corp documents sign-all --json </code></pre><h3>PDF Preview</h3><pre><code>npx corp documents preview-pdf --definition-id bylaws </code></pre><p><strong>Known issue:</strong> <code>preview-pdf</code> fails in <code>process://</code> local transport mode. Use cloud or HTTP server mode for PDF previews.</p><p>Templates: <code>bylaws</code>, <code>operating_agreement</code>, <code>certificate_of_incorporation</code>, <code>articles_of_organization</code>, <code>employment_offer</code>, <code>nda</code>, <code>ip_assignment</code>, etc.</p><h2>Contacts</h2><pre><code>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 </code></pre><p>Categories: <code>employee</code>, <code>contractor</code>, <code>board_member</code>, <code>investor</code>, <code>law_firm</code>, <code>valuation_firm</code>, <code>accounting_firm</code>, <code>officer</code>, <code>founder</code>, <code>member</code>, <code>other</code></p><h2>Agents</h2><p>Agents are autonomous actors that can claim work items and interact with the system:</p><pre><code>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> </code></pre><p><strong><code>agents create</code> flags:</strong></p><ul><li><code>--name <name></code> (required) — agent display name</li><li><code>--prompt <prompt></code> (required) — system prompt for the agent</li><li><code>--model <model></code> — LLM model to use</li></ul><p>Note: Agents are workspace-scoped, not entity-scoped. No <code>--entity-id</code> needed.</p><p>Agent payloads can be size-sensitive — keep skill descriptions and message bodies concise to avoid 500 errors. Use <code>--body-file</code> or <code>--instructions-file</code> for large content.</p><h2>Work Items</h2><pre><code>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> </code></pre><p>Note: <code>--by</code> is required for both <code>claim</code> and <code>complete</code>. Alias: <code>--claimer</code> for claim, <code>--completed-by</code> for complete.</p><h2>Tax</h2><pre><code>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 </code></pre><h2>Key Flags</h2><table><thead><tr><th>Flag</th><th>Description</th><th>Scope</th></tr></thead><tbody><tr><td>------</td><td>-------------</td><td>-------</td></tr><tr><td><code>--json</code></td><td>JSON output (machine-readable)</td><td>Nearly all commands</td></tr><tr><td><code>--dry-run</code></td><td>Preview request without executing</td><td>Most write operations</td></tr><tr><td><code>--entity-id <ref></code></td><td>Scope to an entity</td><td>Entity-scoped commands</td></tr><tr><td><code>--force</code></td><td>Allow security-sensitive updates</td><td><code>config set</code> for <code>api_key</code></td></tr></tbody></table><h2>Important Gotchas</h2><ol><li><strong>C-Corp equity requires board approval</strong> — You must have a <code>resolution_id</code> from a governance vote or written consent before issuing equity on a C-Corp. LLCs do not have this requirement.</li></ol><ol><li><strong><code>active_entity_id</code> must be set</strong> — Most entity-scoped commands require either <code>--entity-id</code> or a configured <code>active_entity_id</code>.</li></ol><ol><li><strong>Dollar sign in descriptions</strong> — <code>$</code> characters in command arguments may be shell-interpolated. In descriptions like <code>"$50K SAFE"</code>, the <code>$50K</code> can become <code>0K</code>. Avoid <code>$</code> or escape it properly.</li></ol><ol><li><strong>SAFE instrument is NOT needed for <code>issue-safe</code></strong> — Unlike <code>issue-equity</code>, the <code>issue-safe</code> command does not require a pre-existing instrument. It creates the SAFE directly.</li></ol><ol><li><strong>Agent payload size</strong> — Large payloads to <code>agents skill</code> or <code>agents message</code> can cause 500 errors. Keep payloads short, or use <code>--body-file</code>/<code>--instructions-file</code>.</li></ol><ol><li><strong>Formation <code>finalize</code> requires complete data</strong> — The staged flow requires <code>--board-size</code> and <code>--company-address</code> on <code>finalize</code> for C-Corps. Missing fields cause validation errors.</li></ol><ol><li><strong><code>demo</code> command</strong> — Use <code>npx corp demo --name "Acme" --minimal</code> for a reliable quick seed. Full scenarios (<code>startup</code>, <code>llc</code>, <code>restaurant</code>) may hit validation edge cases depending on version.</li></ol><ol><li><strong>Monetary values are in cents</strong> — All financial amounts (<code>--amount</code>, <code>--valuation-cap</code>, <code>--enterprise-value</code>, <code>--issue-price-cents</code>, <code>--price-per-share-cents</code>) are in cents. <code>500000</code> = $5,000.</li></ol><ol><li><strong>Role values</strong> — Member/seat roles are <code>director</code>, <code>officer</code>, <code>manager</code>, <code>member</code>, <code>chair</code> — NOT <code>founder</code>. Use <code>founder</code> as a contact category instead.</li></ol><ol><li><strong>Body type values</strong> — Governance body types are <code>board_of_directors</code>, <code>llc_member_vote</code> — NOT <code>board</code>.</li></ol><ol><li><strong>Address formats</strong> — One-shot <code>--member</code> addresses use pipe separator: <code>street|city|state|zip</code>. Staged <code>--address</code> and <code>--company-address</code> use comma separator: <code>street,city,state,zip</code>.</li></ol><ol><li><strong><code>finance activate-account</code></strong> — Bank accounts are created in <code>pending_review</code> state. Use <code>npx corp finance activate-account <account-ref></code> to activate before submitting payments.</li></ol><ol><li><strong>Formation auto-creates board</strong> — Forming a C-Corp automatically creates a Board of Directors governance body. You don't need to <code>create-body</code> separately after formation.</li></ol><ol><li><strong>LLC requires pct</strong> — LLC members require <code>pct</code> (ownership percentage). C-Corp members can use either <code>pct</code> or <code>shares</code>.</li></ol><h2>Workflow Patterns for Agents</h2><h3>Pattern: Form Entity + Issue Equity (C-Corp)</h3><pre><code>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> </code></pre><p>Note: Formation auto-creates a board, so skip <code>create-body</code> + <code>add-seat</code> if using one-shot formation.</p><h3>Pattern: 409A Valuation Approval</h3><pre><code>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 </code></pre><h3>Pattern: Agent Task Loop</h3><pre><code>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" </code></pre><h2>Further Reference</h2><p>For the complete command catalog with all options, run:</p><pre><code>npx corp schema --json </code></pre><p>For help on any specific command:</p><pre><code>npx corp <command> --help </code></pre></div> </div> </div> <div id="tab-versions" class="detail-content"> <div class="detail-section"> <h2>版本历史</h2> <p style="margin-bottom:12px;font-size:14px;color:#94a3b8;">共 1 个版本</p> <ul class="version-list"> <li> <div> <span class="version-tag">v1.0.0</span> <span style="font-size:11px;color:#5b6abf;margin-left:8px;background:#eef0ff;padding:1px 8px;border-radius:10px;">当前</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-05-02 10:06 安全安全 </div> </li> </ul> </div> </div> <div id="tab-security" class="detail-content"> <div class="detail-section"> <h2>安全检测</h2> <p style="color:#94a3b8;">暂无安全检测报告</p> </div> </div>  </div> <script> document.addEventListener('DOMContentLoaded',function(){ document.querySelectorAll('.detail-tab').forEach(function(btn){ btn.addEventListener('click',function(e){ var tab = this.getAttribute('data-tab'); document.querySelectorAll('.detail-tab').forEach(function(b){b.classList.remove('active')}); document.querySelectorAll('.detail-content').forEach(function(c){c.classList.remove('active')}); this.classList.add('active'); var el = document.getElementById('tab-'+tab); if(el) el.classList.add('active'); }); }); }); </script> <div class="footer"> <p>Skill工具集 © 2026</p> </div></body> </html>

TheCorporation.ai Form and Operate

概述