Watch It Run

Your agent does the work; your job is to watch it. Three questions matter: what happened, what's next, and what it's costing.

Events

MCP clients that negotiate the Tasks extension can follow media_generate, research_start, and database_functions_deploy through tasks/get. Task creation returns a durable task ID; retrieval returns the completed domain result, including saved Library references for media and research. Clients without Tasks keep the ordinary job response and use its status operation.

Media Tasks retain the same image previews and resource links as media_get. Temporary media URLs can expire; read media_get or the saved Library file to refresh them. Research Tasks include the saved report and results file IDs and paths. Deployment Tasks require the same company admin access as deployment status reads. Every Tasks retrieval checks current access again.

Tasks cancellation is cooperative: an acknowledgement does not promise that provider work stopped or that a completed deployment was undone. Use domain status reads to check what actually finished.

The MCP Events catalog includes media.generation.completed, media.generation.failed, research.query.finished, and database.function.deploy.finished. Select the company and job when subscribing. A subscription created after completion replays the latest matching outcome; duplicate delivery never starts another operation. Media subscriptions only deliver jobs submitted by the connected account.

Everything meaningful your company's agents do lands in the event stream.

MCP	CLI	API
`events_list`	`cofounder events list`	`GET /cofounder-cli/v1/events`
`events_search`	`cofounder events search`	`GET /cofounder-cli/v1/events/search`
`events_subscriptions_get`	`cofounder events subscriptions get --subscription-id <id>`	`GET /cofounder-cli/v1/events/subscriptions/{subscription_id}`
`events_subscriptions_refresh`	`cofounder events subscriptions refresh --subscription-id <id> --secret-file <path>`	`POST /cofounder-cli/v1/events/subscriptions/{subscription_id}/refresh`
`events_get`	`cofounder events get --event-id <event_id>`	`GET /cofounder-cli/v1/events/{event_id}`
`events_post`	`cofounder events post`	`POST /cofounder-cli/v1/events`
`events_schemas_list`	`cofounder events schemas list`	`GET /cofounder-cli/v1/events/schemas`

cofounder events tail follows new events as they arrive, the closest thing to watching over your agent's shoulder. events post lets an agent record its own milestones, and events schemas list shows the event types you can filter on. A successful post is already stored. For safe retries, choose --event-id before the first call and reuse it. An existing ID returns the original event without overwriting it.

For an existing MCP webhook subscription, events subscriptions get reports whether it exists, when it expires, its retry count, and its recovery cursor. An active subscription with zero failures has unknown delivery health; the read does not probe the callback or prove that an event arrived.

events subscriptions refresh uses your account's existing subscription and callback URL. Pass --cursor to replay a lapsed subscription from that subscription's cursor, or omit it to retain progress. An active subscription always retains its current progress. Read the signing key from --secret-file; the key can be rotated and the callback is verified when required. A deleted subscription or revoked OAuth connection requires a new events/subscribe call from the MCP host. These account tools require a user login; a company API key cannot manage an account's webhook subscriptions.

Watches

A watch is a standing question, such as "any pricing changes at our top competitors?", rechecked daily or weekly. When a recheck finds something new, a watch.event.detected event lands in the stream with a summary and citations. Each recheck is billed to the company, and a company can have up to 10 watches.

MCP	CLI	API
`watches_create`	`cofounder watches create --kind topic --query <text> --cadence 1d`	`POST /cofounder-cli/v1/watches`
`watches_list`	`cofounder watches list`	`GET /cofounder-cli/v1/watches`
`watches_delete`	`cofounder watches delete --watch-id <id>`	`DELETE /cofounder-cli/v1/watches/{watch_id}`

Pass --account-id or --contact-id (not both) to anchor the question to a CRM account or contact. watches delete stops rechecks and billing.

For a live view of managed setup specifically:

cofounder watch company

The roadmap

The roadmap is the company's plan of record: agents work from it, you review it.

MCP	CLI	API
`roadmap_get`	`cofounder roadmap get`	`GET /cofounder-cli/v1/tech-tree`
`roadmap_nodes_get`	`cofounder roadmap nodes get --node-key <key>`	`GET /cofounder-cli/v1/tech-tree/nodes/{node_key}`
`roadmap_nodes_prompt_get`	`cofounder roadmap prompt <key>`, `cofounder roadmap nodes prompt get --node-key <key>`	`GET /cofounder-cli/v1/tech-tree/nodes/{node_key}/prompt`
`roadmap_nodes_complete`	`cofounder roadmap nodes complete --node-key <key> --reason <text>`	`POST /cofounder-cli/v1/tech-tree/nodes/{node_key}/complete`

roadmap get shows the recommended next milestone; roadmap prompt gives you the full brief for a node.

Billing

MCP	CLI	API
`company_billing_get`	`cofounder company billing get`	`GET /cofounder-cli/v1/company/billing`
`company_billing_usage_get`	`cofounder company billing usage get`	`GET /cofounder-cli/v1/company/billing/usage`
—	`cofounder company billing runs list`	`GET /cofounder-cli/v1/company/billing/runs`
`company_billing_transactions_list`	`cofounder company billing transactions list`	`GET /cofounder-cli/v1/company/billing/transactions`
`company_billing_top_up`	`cofounder company billing top-up`	`POST /cofounder-cli/v1/company/billing/top-ups`
`company_billing_transactions_retry`	`cofounder company billing transactions retry <transaction-id>`	`POST /cofounder-cli/v1/company/billing/transactions/{transaction_id}/retry`

Top-ups and auto-recharge amounts are $10 to $5,000.

runs list shows spend per agent run, with charges that carry no run grouped into one unattributed bucket.

If a purchase or charge didn't go through, transactions retry tries it again for the same amount; take the id from transactions list. If a resource failed to provision for billing reasons, retry it through cofounder company billing resources retry --binding-id <id>.

Auto-recharge

Auto-recharge buys more credit from the saved card when your balance runs low, so paid work doesn't stop. It charges real money, so turning it on requires --consent, and changing it takes a company admin.

MCP	CLI	API
`company_billing_auto_recharge_get`	`cofounder company billing auto-recharge get`	`GET /cofounder-cli/v1/company/billing/auto-recharge`
`company_billing_auto_recharge_update`	`cofounder company billing auto-recharge update --enabled --consent --threshold-cents <cents> --amount-cents <cents> --monthly-limit-cents <cents>`	`PUT /cofounder-cli/v1/company/billing/auto-recharge`
—	`cofounder company billing auto-recharge retry`	`POST /cofounder-cli/v1/company/billing/auto-recharge/retry`

When the balance would drop below --threshold-cents, Cofounder buys --amount-cents of credit, up to --monthly-limit-cents a month. If no card is saved yet, update returns a link to add one, and nothing is charged until that's done. --no-enabled stops future charges. If a charge needs the cardholder to confirm it, auto-recharge retry returns a link for that.

Budgets

A budget is a monthly spending limit on the company's spend that resets at the start of each UTC month. Agents can read it, create it, or lower it, but only the company's payer can raise or remove it, on the billing dashboard; asking for a higher limit returns a 403 with code spending_limit_raise_requires_payer. A charge that would cross the limit is refused with a 402 error with code spending_limit_exceeded that links to the dashboard.

A playbook run has its own lifetime budget. Set it per run with --budget-cents on playbooks start or update (see the playbooks guide); a charge past it fails with the same spending_limit_exceeded code.

MCP	CLI	API
`company_billing_budgets_list`	`cofounder company billing budgets list`	`GET /cofounder-cli/v1/company/billing/budgets`
`company_billing_budgets_set`	`cofounder company billing budgets set --scope company --limit-cents <cents>`	`PUT /cofounder-cli/v1/company/billing/budgets`

When a charge is refused

A charge the company's balance can't fund is refused with funding_required (HTTP 402, CLI exit code 5). details.reason says why:

`reason`	Meaning	What to do
`insufficient`	The balance is below the charge.	The payer adds credits.
`refilling`	An automatic recharge is in flight.	Retry after `retry_after_seconds`.
`recharge_failed`	The last automatic recharge was declined.	The payer fixes the card or adds credits.
`needs_authentication`	The card needs the cardholder to confirm.	The payer confirms the card or adds credits.
`monthly_recharge_limit`	Automatic recharge hit its monthly limit.	The payer raises the limit or adds credits.
`paused`	Billing is locked by an unpaid balance.	The payer pays what is owed (`owed_cents`).

Referrals

Referring another founder earns credit:

MCP	CLI	API
`referrals_link_get`	`cofounder referrals link get`	`GET /cofounder-cli/v1/referrals/link`
`referrals_history_get`	`cofounder referrals history get`	`GET /cofounder-cli/v1/referrals/history`

link get prints your link and totals; history get lists each person you referred and whether their credit was granted.

Diagnostics

When something feels off on your machine rather than the company's, run:

cofounder doctor

It checks the CLI's own environment: auth, config, connectivity.

Support

Open a ticket with the Cofounder team and keep the thread going from the terminal:

MCP	CLI	API
`support_create`	`cofounder support create --subject <text> --description <text>`	`POST /cofounder-cli/v1/support/tickets`
`support_list`	`cofounder support list`	`GET /cofounder-cli/v1/support/tickets`
`support_get`	`cofounder support get --ticket-id <id>`	`GET /cofounder-cli/v1/support/tickets/{ticket_id}`
`support_reply`	`cofounder support reply --ticket-id <id> --body <text>`	`POST /cofounder-cli/v1/support/tickets/{ticket_id}/reply`

Creating a ticket sends the supplied fields to Cofounder Support. Add --runtime, --runtime-version, or --model when they help diagnose the problem. Use --context-excerpt for a deliberately selected, relevant excerpt; leave out full conversations, raw transcripts, credentials, and unrelated personal data. Cofounder does not retrieve conversation history automatically.

Cofounder generates and returns a support request ID when you omit --support-request-id. Reuse that ID when retrying to request best-effort deduplication. You only see your own tickets.

Replies can include separate guidance for people and their agents:

cofounder support reply --ticket-id <id> \
  --body "Here is the update." \
  --for-humans "The issue is fixed. Please try again." \
  --for-agents "Retry the failed command, then verify the resulting state."

--body is required. Either audience section is optional. The reply appends literal <for_humans>...</for_humans> and <for_agents>...</for_agents> sections so the full message can be copied into an agent. API and MCP callers use for_humans and for_agents. The combined reply, including section tags, must fit within 12,000 characters; supplied fields must contain nonblank text.

Upload screenshots

Upload private screenshots to S3, Cofounder's file storage. No selected company or paid subscription is required. The CLI handles uploads when you pass local files:

cofounder support create --subject 'Broken preview' --description 'The page stays blank.' \
  --screenshot ./preview.png --screenshot ./console.png

Repeat --screenshot for up to five PNG, JPEG, or WebP files, at most 10 MiB each. The CLI checks all files, generates one request ID, uploads each file directly to S3, finalizes them, and creates the ticket. Use --dry-run to preview the fields and local paths without reading files or sending requests.

For an existing upload, use --screenshot-upload-id with its explicit --support-request-id. Local-file and upload-ID flags cannot be combined. If a response is uncertain, the error includes the request ID, known upload IDs, and a command to inspect progress. Keep those IDs and resume with finalized upload IDs; do not rerun the local-file command and upload another set. Before ticket submission, cleanup only touches this invocation's unused uploads. Uncertain finalization or ticket responses preserve them for inspection.

MCP agents use the separate upload operations below, then pass the finalized IDs to support_create.

MCP	CLI	API
`support_uploads_start`	`cofounder support uploads start --support-request-id <id> --filename <name> --content-type <type> --size-bytes <bytes>`	`POST /cofounder-cli/v1/support/uploads`
`support_uploads_finalize`	`cofounder support uploads finalize --support-request-id <id> --upload-id <id> --parts <json>`	`POST /cofounder-cli/v1/support/uploads/{upload_id}/finalize`
`support_uploads_get`	`cofounder support uploads get --support-request-id <id>`	`GET /cofounder-cli/v1/support/uploads`
`support_uploads_cancel`	`cofounder support uploads cancel --support-request-id <id> --upload-id <id>`	`DELETE /cofounder-cli/v1/support/uploads/{upload_id}`

Upload flow:

Use one request ID for the group. start returns an upload ID and temporary URL for each file; specify its type, such as image/png, and exact byte size.
HTTP PUT the file to that URL. Keep the response's ETag header: it identifies the uploaded part.
Call finalize with both IDs and --parts '[{"part_number":1,"etag":"<ETag>"}]' to validate the stored image.
Create the ticket with the same --support-request-id and repeat --screenshot-upload-id <id> for each finalized file. MCP callers supply screenshot_upload_ids to support_create.

cofounder support create --subject 'Screenshot example' --description 'The error appears here.' \
  --support-request-id <request-id> --screenshot-upload-id <first-upload-id> \
  --screenshot-upload-id <second-upload-id>

Intercom copies the images into its own storage. support create and support get return screenshot names, sizes, types, and temporary download URLs. Read the ticket again to refresh expired download URLs. Intercom controls the order in which attachments are displayed.

get shows progress, including confirmed conversation and ticket IDs, and refreshes pending upload URLs. Once submission begins, the screenshot list is frozen: retry with the same request ID and ordered upload IDs. An unresolved conversation creation must be inspected before another ticket is created. After the 24-hour upload record expires, use support get --ticket-id <ticket-id> to read the existing ticket; support create cannot verify the original upload IDs. cancel deletes a file before submission and frees its slot once cleanup succeeds. MCP agents must read the file and make the HTTP request themselves; the hosted tool can't open local paths.

Limits: five static PNG/JPEG/WebP files per request, 10 MiB each, 50 million pixels per image, and 20,000 pixels per side. Extension, MIME type, and bytes must match. Each user gets 25 start attempts per hour. URLs last one hour; references expire 24 hours after the first reservation. Files stay temporary and are subject to abandoned-upload cleanup.

Retry rules:

Lost start response: call get before reserving another slot.
Lost finalize response: check progress and retry finalize. If S3 hasn't confirmed completion, you can't cancel yet; check again later.
Failed cancel: retry cancel. You can't finalize until cleanup finishes.

Next steps

The Advanced section covers where secrets live, multiple companies, API keys, and the rest of the MCP surface.