@usefillo/cli 0.8.0 → 0.10.0

package/README.md

@@ -1,9 +1,23 @@
-# @usefillo/cli
+<p align="center">
+  <a href="https://fillo.so">
+    <img src="https://fillo.so/brand/readme-banner.png" alt="Fillo — forms inside your product, with your UI." />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://fillo.so/docs">Docs</a> ·
+  <a href="https://fillo.so/guides">Guides</a> ·
+  <a href="https://fillo.so/agents">Agents</a> ·
+  <a href="https://fillo.so/changelog">Changelog</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefillo/cli"><img src="https://img.shields.io/npm/v/@usefillo/cli" alt="npm version" /></a>
+  <img src="https://img.shields.io/npm/l/@usefillo/cli" alt="MIT license" />
+</p>
 
 `fillo` — create and publish [Fillo](https://fillo.so) forms from your terminal. Auth once, then your coding agent does the rest.
 
-### 📚 Full documentation → **[fillo.so/docs](https://fillo.so/docs)**
-
 ```sh
 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
@@ -11,95 +25,35 @@ npx @usefillo/cli push form.json --handle hello --stage # stage for dashboard re
 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](https://fillo.so/agents) for provider-specific setup. The API
+Commands: `init`, `login`, `logout`, `whoami`, `push <file|->`, `list`,
+`agent bootstrap`, `agent connect`, `agent event`, and `skill install`. Run
+`npx @usefillo/cli --help` for flags. The canonical skill is
+one portable Agent Skills bundle. The default command installs it in the shared
+`.agents/skills` path and Claude Code's `.claude/skills` path. Hosts with another
+location can use `skill install --dir <agent-skill-directory>`, so the same
+bundle works without provider-specific forks. See
+[fillo.so/agents](https://fillo.so/agents) for setup. The API
 commands target
 `https://fillo.so` by default (set `FILLO_API` to override).
 
-## Safe schema staging
+## Stage instead of publish
 
-After `fillo login`, use `--stage` to create or replace a code draft without
-taking the published form offline:
+`--stage` creates or replaces a reviewable draft without taking the published
+form offline; a plain authenticated `push` publishes directly.
 
 ```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.
+CI staging with least-privilege sync tokens, pushing a schema from stdin, and
+the raw sync endpoint are covered in the CLI guide:
+[fillo.so/docs/cli](https://fillo.so/docs/cli). The agent handoff and progress
+protocol (`fillo agent event`) live at
+[fillo.so/agents](https://fillo.so/agents).
 
-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.
+A Fillo browser handoff supplies an `agent bootstrap` command. It installs the
+skill and connects the live setup in one run. With `--account`, it also opens
+Fillo so the user can approve the exact workspace before the agent continues.
 
 ## Links