CLI & publishing

Choose the credential by workflow

Connect the CLI

Use login for an existing Fillo account. It opens the browser approval page and catches the token on a local loopback, with nothing to copy or type. Headless, SSH, CI, and agent sessions fall back to a device code automatically; force it with --headless.

After an ordinary login, project list shows every site/app in the billed workspace. project create makes and selects an isolated project; project select deliberately retargets later commands. A project-specific agent handoff stays pinned and cannot enumerate, create, or select sibling projects.

Use agent bootstrap when the app has no workspace yet: one command provisions a capped email-backed preview workspace and installs the Build with Fillo skill. init provisions the same preview workspace without the skill. Do not create a second workspace when an existing team workspace is the intended target.

claim saves a preview workspace to an account from the emailed link and connects the terminal that ran it. logout removes the stored login but keeps the default project's preview key. Commands target https://fillo.so unless FILLO_API (or --api on login and agent commands) points at another deployment.

# Existing account, workspace, and project
npx @usefillo/cli@latest login
npx @usefillo/cli@latest whoami

# Create an isolated site/app under the same bill, or select an existing one
npx @usefillo/cli@latest project create "Customer site"
npx @usefillo/cli@latest project list
npx @usefillo/cli@latest project select customer-site-a1b2c3

# New workspace + agent skill in one step
npx @usefillo/cli@latest agent bootstrap --email you@company.com

# New preview workspace only (no skill install)
npx @usefillo/cli@latest init --email you@company.com

# Save the preview to an account later; sign out
npx @usefillo/cli@latest claim
npx @usefillo/cli@latest logout

Push 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.
• --stage creates or replaces a side-by-side draft revision. With a stable handle, --draft remains a compatibility alias for --stage; without a handle it creates a new one-off draft.
• fillo status <formId|handle> is read-only: it reports the form's status and live URL, plus any storage warning with the settings link that resolves it.
• A file_upload field still needs a connected storage destination before the CLI can publish the form.
• JavaScript schema files require the explicit --allow-code flag 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

# Stages a draft beside the live form for dashboard review
npx @usefillo/cli@latest push form.json --handle onboarding --stage

npx @usefillo/cli@latest list
npx @usefillo/cli@latest status onboarding

Operate the workspace from the terminal

Day-two operations do not need the dashboard: select the intended project, promote a staged revision, send one safe test response, and manage project keys, responses, storage, Slack, webhooks, settings, and workspace members from the same login.

• keys create scopes with --preset read|agent|full (or explicit --scopes) and shows the plaintext key once; keys list and keys revoke <keyId> manage the rest of the lifecycle.
• storage connect s3 runs headless (r2 is an accepted alias); drive and box finish in a signed-in browser.
• Every command takes --json for machine-readable output, and agent mode engages automatically (non-TTY or FILLO_AGENT=1): no ANSI, no browser auto-open, and do-not-retry-login guidance.
• delete form and delete workspace require a typed confirmation; automation passes --confirm with the exact title. --yes never skips the guard.

npx @usefillo/cli@latest project list
npx @usefillo/cli@latest project select customer-site-a1b2c3
npx @usefillo/cli@latest publish onboarding
npx @usefillo/cli@latest test-response onboarding answers.json
npx @usefillo/cli@latest keys create --name automation --preset agent
npx @usefillo/cli@latest responses export onboarding --out responses.csv
npx @usefillo/cli@latest storage connect s3
npx @usefillo/cli@latest webhooks list onboarding
npx @usefillo/cli@latest settings get onboarding
npx @usefillo/cli@latest members

Sync safely with a publishable key

1. 1

   Copy the project 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.

2. 2

   Use one stable code handle

   defineForm({ id }), JSX, client.syncForm(handle, …), and the sync API all use an ID that is unique in the workspace. Sync returns a formId; use it for form links and submissions.

3. 3

   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.

4. 4

   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 its formId or hosted slug. Fetching and submitting a published form does not need a publishable key. Pass a client when you use a custom API origin or build your own renderer. Add a publishable key only when syncing forms from code.

Keep the local handle and the Fillo formId distinct. The handle is your idempotent sync identity inside one project. The formId is the durable Fillo record returned by sync and shown by the CLI.

Install the project skill

Install the Build with Fillo skill before asking a coding agent to add a form. One command installs the provider-neutral bundle in the shared Agent Skills path and Claude Code; use --dir for any host with another skill directory.

npx @usefillo/cli@latest skill install

Next steps