@usefillo/cli

@usefillo/cli

fillo — create and publish Fillo forms from your terminal. Auth once, then your coding agent does the rest.

📚 Full documentation → fillo.so/docs

npx @usefillo/cli init --email [e-mail] # start a workspace and email its link
npx @usefillo/cli login                         # connect an existing account in the browser
npx @usefillo/cli push form.json --handle hello --stage # stage for dashboard review
npx @usefillo/cli@latest skill install           # install the project Agent Skill

Commands: init, login, logout, whoami, push <file|->, list, agent, and skill install. Run npx @usefillo/cli --help for flags. The canonical skill is one portable SKILL.md bundle: Codex, Cursor, GitHub Copilot agent surfaces, and Gemini CLI share .agents/skills, while Claude Code uses .claude/skills. See fillo.so/agents for provider-specific setup. The API commands target https://fillo.so by default (set FILLO_API to override).

Safe schema staging

After fillo login, use --stage to create or replace a code draft without taking the published form offline:

npx @usefillo/cli push form.json --handle customer-onboarding --stage

With a stable handle, --draft remains a compatibility alias for --stage. The legacy fillo push form.json --draft form without a handle still creates a new one-off draft, so it cannot take an existing live form offline. A plain authenticated push still publishes directly, so use it only when immediate publication is intentional.

The CLI also reads one JSON schema from stdin. This is useful for agents and CI that already hold the canonical schema and should not leave another file behind:

generate-form-schema | npx @usefillo/cli push - --handle customer-onboarding --stage

For non-interactive server or CI staging, create a least-privilege token in Fillo's Settings > Developers page and store it in the environment. The token can stage schemas, but cannot publish forms or read responses.

FILLO_SYNC_TOKEN="$YOUR_CI_SECRET" \
  npx @usefillo/cli push form.json --handle customer-onboarding --stage

A server can also call the stage-only endpoint directly:

POST /api/v1/forms/sync
Authorization: Bearer fsync_…
Content-Type: application/json

{"id":"customer-onboarding","schema":{"version":1,"title":"Onboarding","pages":[{"id":"main","blocks":[{"id":"email","kind":"email","label":"Email","required":true}]}],"settings":{}}}

Send the bearer alone and omit key from the body. Combining both credential types is rejected as ambiguous_sync_credentials.

Store FILLO_SYNC_TOKEN in the platform's secret manager. Do not commit it, pass it as a command-line flag, or print it in logs. Tokens have no scheduled expiry by default, but stop working if their creator loses manager access or account/workspace deletion begins. Revoke and rotate them from the Developers page.

Agent progress

The browser handoff supplies a run ID and short-lived progress token. Coding agents use fillo agent event to keep that onboarding session in sync. Report --form-id as soon as a form exists so Fillo can resume on the correct form, watch for its first response, and open the right dashboard page.

npx @usefillo/cli agent event \
  --run "RUN_ID_FROM_HANDOFF" --token "PROGRESS_TOKEN_FROM_HANDOFF" \
  --status needs_action --message "Publish the synced form" \
  --action publish_required \
  --form-id "FORM_ID_FROM_SYNC" --form-status draft

--action accepts claim_required, storage_required, or publish_required. --form-status accepts draft or published. --app-url is optional and accepts only an HTTP(S) localhost or loopback URL; Fillo stores only its origin. Saving a preview workspace to an account stays in Fillo and is not reported through agent progress events. Never print, save, or commit the progress token.

An existing-account handoff asks the agent to run the handoff-specific fillo login --api … --run … --token … command from the copied prompt, followed by fillo agent connect --account. The user explicitly chooses and approves the workspace in Fillo. A general or older CLI login cannot attach that handoff. The CLI keeps its account identity and token private and returns only the workspace name and public pk_ key to the agent. Existing-account handoffs stage schema changes through the authenticated CLI; the pk_ key remains for registered code-form resolution in browser code. Published form reads and responses work by form id independently.

Links

• Docs: fillo.so/docs
• Website: fillo.so

MIT licensed.