DocsCLI & publishing
CLI, publishing, and keys
Choose the right credential and publish lifecycle for terminal, browser, and agent workflows.
Choose the credential by workflow
| Workflow | Credential | Lifecycle |
|---|---|---|
| Render a published form by formId or slug | No key | The dashboard's published version loads and accepts responses. |
| Sync a code-defined form from browser or app code | pk_ publishable key | Claimed workspaces stage changes for human review before publication. |
| Push reviewed JSON from a terminal | Private CLI token from fillo login | Publishes directly by default; --draft takes the form offline as a draft. |
| Connect Zapier | Private API token | Authorizes Zapier form discovery and response hook subscriptions. |
Public and private keys are not interchangeable
A pk_ key is safe to expose and can sync schemas, but cannot manage the workspace. CLI and Zapier API tokens are private management credentials; keep them out of client bundles and logs.
Connect the CLI
Use login for an existing Fillo account. It opens a browser, asks you to choose the exact workspace, and stores the resulting CLI token in the local Fillo config.
Use init only when you need a new capped preview workspace. It requires an email so Fillo can send the durable claim link; do not create a second workspace when an existing team workspace is the intended target.
# Existing account and workspace
npx @usefillo/cli@latest login
npx @usefillo/cli@latest whoami
# New preview workspace only
npx @usefillo/cli@latest init --email you@company.comPush a reviewed schema
push accepts JSON by default. Give the form a stable handle so later pushes update the same Fillo form and preserve its formId, hosted slug, existing responses, storage selection, and separate webhook/integration records. The incoming schema replaces the stored schema wholesale, including schema-backed settings such as notification and receipt controls.
- A normal authenticated push replaces the live schema for that stable handle and clears an older staged revision. Review the JSON before running it against production.
--draftsets the form status to draft; it is not a side-by-side draft revision. Publish it later from the dashboard.- A
file_uploadfield still needs a connected storage destination before the CLI can publish the form. - JavaScript schema files require the explicit
--allow-codeflag because loading them executes local code. Prefer JSON for reviewable automation.
# Creates or updates and publishes immediately after login
npx @usefillo/cli@latest push form.json --handle onboarding
# Creates a draft, or takes an existing live form offline as a draft
npx @usefillo/cli@latest push form.json --handle onboarding --draft
npx @usefillo/cli@latest listSync safely with a publishable key
Copy the workspace key
Open Settings → Developers → Form sync. Put the
pk_value in a public environment variable when client code needs it; it is intentionally browser-visible.Use one stable code handle
defineForm({ id }), JSX authoring,client.syncForm(handle, …), and the sync API all use a workspace-unique handle. The sync response returns Fillo's canonicalformId; keep that id for links and completion handoffs.Review before publishing
In a claimed workspace, a first sync creates a draft and later changes stage beside the published version. A human publishes from the dashboard. A capped unclaimed preview may apply code sync live until it is claimed.
Optionally restrict browser origins
Allowed origins reduce accidental use from other sites, but callers can forge an Origin header. Review-before-publish remains the security boundary.
Embed the published result
Once a form is published, render it with the canonical formId or hosted slug. Published fetch and submission do not need a publishable key, and the default renderer creates its own default client. Pass a client explicitly for a custom API origin or when a headless/custom renderer calls uploads or submissions; add a publishable key only for code sync.
Keep the local handle and the Fillo formId distinct. The handle is your idempotent sync identity inside one workspace. The formId is the durable Fillo record returned by sync and shown by the CLI.
Install the agent skill
The CLI ships one provider-neutral Build with Fillo skill. The default shared path works with Codex, Cursor, GitHub Copilot agent surfaces, and Gemini CLI; Claude Code uses its own discovery path. Install it in the repository before asking a coding agent to author or integrate a form.
npx @usefillo/cli@latest skill install
# Claude Code uses .claude/skills
npx @usefillo/cli@latest skill install --agent claude