@usefillo/cli 0.5.1 → 0.8.0

package/README.md

@@ -5,11 +5,101 @@
 ### 📚 Full documentation → **[fillo.so/docs](https://fillo.so/docs)**
 
 ```sh
-npx @usefillo/cli init                          # provision a workspace — no signup
-npx @usefillo/cli push form.json --handle hello # create/update a form from a JSON schema
+npx @usefillo/cli init --email you@company.com # 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`. Run `npx @usefillo/cli --help` for flags. Targets `https://fillo.so` by default (set `FILLO_API` to override).
+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](https://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:
+
+```sh
+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:
+
+```sh
+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.
+
+```sh
+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:
+
+```http
+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.
+
+```sh
+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