fimo 2.10.1-staging.1 → 2.10.1-staging.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/assets/skills/fimo-cli/SKILL.md +57 -139
  2. package/assets/skills/fimo-cli/SKILL.studio.md +42 -0
  3. package/assets/skills/fimo-cli/references/branches.md +43 -106
  4. package/assets/skills/fimo-cli/references/content/bulk.md +48 -0
  5. package/assets/skills/fimo-cli/references/content/entries.md +54 -0
  6. package/assets/skills/fimo-cli/references/content/localized.md +56 -0
  7. package/assets/skills/fimo-cli/references/content/schemas.md +29 -0
  8. package/assets/skills/fimo-cli/references/content/sql.md +57 -0
  9. package/assets/skills/fimo-cli/references/content.md +33 -272
  10. package/assets/skills/fimo-cli/references/deploy.md +35 -126
  11. package/assets/skills/fimo-cli/references/domains.md +38 -131
  12. package/assets/skills/fimo-cli/references/forms.md +1 -1
  13. package/assets/skills/fimo-cli/references/init.md +36 -170
  14. package/assets/skills/fimo-cli/references/locales.md +2 -2
  15. package/assets/skills/fimo-cli/references/projects.md +1 -1
  16. package/assets/skills/fimo-code/references/design.md +42 -126
  17. package/assets/skills/fimo-migration/SKILL.md +114 -408
  18. package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
  19. package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
  20. package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
  21. package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
  22. package/assets/skills/fimo-migration/references/qa/results.md +78 -0
  23. package/assets/skills/fimo-migration/references/qa.md +102 -383
  24. package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
  25. package/assets/skills/fimo-migration/references/setup.md +90 -0
  26. package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
  27. package/assets/skills/fimo-migration/references/workers.md +1 -1
  28. package/assets/skills/fimo-migration/references/workflow.md +117 -171
  29. package/assets/skills/fimo-studio/SKILL.md +12 -11
  30. package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
  31. package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
  32. package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
  33. package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
  34. package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
  35. package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
  36. package/dist/cli/bundle.json +1 -1
  37. package/dist/cli/index.js +38 -17
  38. package/package.json +8 -8
  39. package/templates/astro/package.json +3 -3
  40. package/templates/nextjs/package.json +4 -4
  41. package/templates/react-router/package.json +5 -5
  42. package/templates/sveltekit/package.json +3 -3
  43. package/templates/vite/package.json +5 -5
@@ -9,150 +9,68 @@ description: >-
9
9
 
10
10
  # Fimo CLI
11
11
 
12
- The `fimo` CLI is the workflow surface for Fimo. Fimo connects content, media, forms, analytics, editing, and hosting to web applications. The CLI handles site creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, AI credit inspection, and AI agent setup.
12
+ This skill covers CLI workflows. For code (schema JSON, generated clients, primitives, framework adapters), load `fimo skills get fimo-code`. For the flags of one command, run `fimo <command> --help`.
13
13
 
14
- This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), load the `fimo-code` skill on demand with `fimo skills get fimo-code`, using the invocation prefix below.
14
+ ## Every task
15
15
 
16
- Use `fimo <command> --help` for full flag details on any command.
17
-
18
- > Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
19
-
20
- ## Shared site knowledge
21
-
22
- Before site planning, recommendations, design, copy, content, or code work, read the site's
23
- knowledge: `fimo knowledge get --project <id> --json` (omit `--project` in a linked checkout).
24
- Use the selected CLI invocation. Load `fimo skills get fimo-cli --ref knowledge` for refresh,
25
- empty-state, and explicit-write rules. This prerequisite also applies when entering this skill directly.
26
-
27
- ## Running the CLI
28
-
29
- Use **`npx fimo@latest`** by default. If the initiating prompt supplies another Fimo CLI selector, such as `npx fimo@staging` or `npx fimo@0.14.0`, preserve that selector for every Fimo command in the same flow. Do **not** install `fimo` globally.
30
-
31
- The examples in this skill and its references use `fimo <command>` as shorthand. Execute them with the selected invocation above.
32
-
33
- ## Output for agents: `--json` is the stable contract
34
-
35
- Every command accepts a global `--json` flag (or `FIMO_OUTPUT=json` env) and emits exactly one structured envelope on stdout:
16
+ - **Invocation:** run `npx fimo@latest`, unless the prompt gives another selector, such as `npx fimo@staging` or `npx fimo@0.14.0`. Then use that selector for every Fimo command in the flow. Do not install `fimo` globally. This skill writes `fimo` for the selected invocation.
17
+ - **Site knowledge:** before planning, recommendations, design, copy, content, or code work, read `fimo knowledge get --json` (add `--project <id>` outside a linked checkout). Rules: `--ref knowledge`.
18
+ - **Project link:** `.fimo/project.json` links the folder to the site. Never edit it.
19
+ - **Branch:** site commands act on the Fimo Branch that matches the current git branch, and print its name. `--branch <name>` changes the Branch for one command. Analytics reads use `prod` by default. Switch Branches with `fimo checkout <name>` (`--ref branches`).
20
+ - **Output:** pass `--json` and read `data`. Branch on `error.code`, not on the message, and follow `hint`. JSON mode never prompts, so give each answer as a flag (`--yes`, `--org <id>`, `-m <message>`).
36
21
 
37
22
  ```json
38
23
  { "status": "ok", "command": "<name>", "schema_version": 1, "data": { ... }, "hint"?: "...", "warnings"?: [...] }
39
24
  { "status": "error", "command": "<name>", "schema_version": 1, "error": { "code": "UPPER_SNAKE_CASE", "message": "...", "hint"?: "..." } }
40
25
  ```
41
26
 
42
- Branch on `error.code`, never on `error.message`. The envelope shape is versioned — `schema_version: 1` is stable; any breaking change bumps the version. Per-command `data` shapes are documented in `apps/cli/CLAUDE.md` (consumers of this skill don't normally need to read it, but it's the source of truth).
43
-
44
- For shell composition use plain pretty mode (`cd $(fimo …)`); for structured parsing use `--json`. JSON mode disables interactive prompts — commands that need a confirmation fail fast unless every required arg is on the command line (`--yes`, `--org`, etc.). Locale lifecycle commands use `CONFIRMATION_REQUIRED` and require `--yes`; other older commands may use `NON_INTERACTIVE_REFUSAL`.
45
-
46
- Pretty output may hide URLs behind clickable labels. Agents should use `--json` and read `data`.
47
-
48
- ## Critical: `.fimo/project.json` is the project link
49
-
50
- A Fimo site is identified by `.fimo/project.json`, written by `fimo init`. This file connects the local directory to the remote Fimo site. **Never edit it manually.** Most CLI commands find it by walking up from the cwd.
51
-
52
- ## Critical: commands target the Branch matching the current git branch
53
-
54
- A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Site-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. Analytics reads are the exception: they default to canonical `prod`, independent of the checkout; see `references/analytics.md`. Annotation writes keep the current or explicit Branch. New sites start on `main`. Override for a single command with the canonical `--branch <name>` flag; the removed `--env <name>` spelling is rejected. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
55
-
56
- ## Quick Start
57
-
58
- ```bash
59
- fimo login # authenticate via browser
60
- fimo skills install # install the global Fimo skill for your AI tools
61
- fimo init my-site --org <id> # one-stop setup: sign in, create/link a project, install deps + skills. Use the org **id** from `fimo orgs list`, NOT the slug.
62
- fimo init my-react-site --framework react-router --org <id> --yes --no-skills # canonical React Router template
63
- fimo init --project-id <id> my-site # set up a project by ID: scaffold a newly created project or clone existing code
64
- fimo new my-site --yes --json # create a site without an account; a person claims it within 72 hours. Run `fimo new --instructions` for the full guide
65
- fimo claim --json # inside a `fimo new` site: the claim link and claim state
66
- fimo clone # interactively choose an existing project to clone locally
67
- cd my-site # then load skills on demand: fimo skills get fimo-code
68
- pnpm dev # run the app locally (use the project's PM: pnpm/npm run/yarn/bun) — your iteration loop
69
- fimo credits # inspect the owning org's AI credit balance (read-only)
70
- fimo history list # inspect this Branch's restore points
71
- fimo validate # run all checks + codegen; fails on missing DB labels
72
- fimo deploy # ON-DEMAND: hosted project preview (runs validate internally)
73
- fimo deploy --publish # ON-DEMAND: publish live (only when the developer says "ship it")
74
- ```
75
-
76
- New sites use the Next.js App Router template by default. Fimo's canonical React Router template is selected explicitly with `--framework react-router`; use `--framework vite` for a React SPA.
77
-
78
- The working loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), ask the developer what they want, edit, and iterate against the live localhost server. Outside the first-time onboarding rule below, `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted project preview or to go live, and only on their signal (see `references/deploy.md`).
79
-
80
- `fimo validate` is the single entrypoint for "prove this project is ready" — it covers schema/form codegen, route metadata checks, lint, and missing label checks for `i18n.defaultLocale` from `.fimo/config.json` (fallback: `en`). Use `fimo labels set` / `set-many` to create or update label values in the DB. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
81
-
82
- Keep `fimo validate --json` at the front of the project's `build` script, which is where the bundled templates put it. The hosted build runs that script, so validation runs on the exact code being published and a rejected build reports the failing rule instead of a generic build error. Removing it is the developer's call, but do not drop it while editing `package.json` for other reasons.
83
-
84
- **`fimo validate` does not type check.** Run the project's own `typecheck` or `check` script after changing code.
85
-
86
- ## Decision Tree
87
-
88
- Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
89
-
90
- - "Create a new Fimo site / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
91
- - "Add a content type / blog / products / content schemas / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
92
- - "Declare Pages routes / configure Pages sources or route params / control what Studio shows for a route" → `references/pages.md`
93
- - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `fimo skills get fimo-code --ref forms` for the JSON spec and generated client**
94
- - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
95
- - "Upload, inspect, replace, safely remove, or permanently destroy an image / hero / cover / existing media file" → `references/assets.md` **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
96
- - "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape if you'll plug the result into UI**
97
- - "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ run `fimo skills get fimo-code --ref labels` and load the detected framework reference**
98
- - "Enable locales / configure default locale / integrate an existing locale system" → `references/locales.md` **+ run `fimo skills get fimo-code --ref locales` and load the detected framework locale reference**
99
- - "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
100
- - "Deploy / publish / go live / push my changes" → `references/deploy.md`
101
- - "Add a redirect / security headers / CSP / HSTS / clean URLs / trailing slash" → `references/hosting.md`
102
- - "Get the preview URL / open the preview / what's the URL for this Branch / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
103
- - "Check the site in a browser / SEO check / broken links / missing titles, descriptions or alt text / `fimo site check` / is my site accessible / a11y or WCAG check / measure LCP or Web Vitals / why is the page slow / inspect network requests or console errors / Lighthouse score" → `references/site-checks.md`
104
- - "Schedule a command / cron / nightly publish / recurring checks / `fimo schedules`" → `references/schedules.md`
105
- - "Set env vars / configure API keys / add project secrets / local `.env.local` / `fimo vars` / `fimo secrets`" → `references/project-vars-and-secrets.md`
106
- - "React to form submissions / publish changes / analytics reports / media activity / send events to Resend, Slack, GitHub, Zapier, or an HTTP endpoint / configure or debug outbound webhooks" → `references/webhooks.md`
107
- - "Use a connected app / Google Search Console / clicks, impressions, rankings, keywords from Google / Google Analytics / GA4 users, sessions, traffic sources, key events / enable provider tools / integrations / add, inspect, search, or run an MCP server / `fimo integrations` or `fimo mcp`" → `references/integrations.md`
108
- - "Firecrawl / scrape a public website / competitor research / agent web research" → `references/integrations.md` **+ load `references/integrations/firecrawl.md`**
109
- - "Check credits / credit balance / can I keep using AI / billing credits / running low / how many credits are left" → `references/credits.md`
110
- - "List history / create a restore point / recover content and code / restore a previous version / snapshot usage or retention" → `references/history.md`
111
- - "Create a Branch / feature Branch / switch Branches / merge Branches / diff two Branches / Branch status / what changed on this Branch / sync from parent / cut a release / tag a version / go to prod" → `references/branches.md`
112
- - "List my projects / clone an existing project locally / check out a project / delete this project / unpublish / rename the project / manage projects across the org" → `references/projects.md`
113
- - "Migrate an existing Webflow / Framer / Squarespace / Wix / Carrd site from only a published URL" → load the `fimo-migration` skill, set the target up with `fimo migrate init <dir>`, and read the published site yourself with a browser — the CLI does not crawl it
114
- - "Put my existing site or app on Fimo / link or deploy the app in this folder / host the site I built" → load the `fimo-migration` skill and follow its source-backed, same-framework path: `fimo link` keeps every word typed in the code, which Studio cannot edit, until the migration's content pass moves it to labels and the CMS
115
- - "Migrate from an exported project, source repository, Webflow code export plus CMS CSVs, Framer CMS CSVs, Squarespace XML/CSV, Wix CSVs, Carrd/static export, or downloaded site files" → load the `fimo-migration` skill and use the source repo/export as the migration source of truth
116
- - "How do AI agents read my site / markdown for agents" → `references/deploy.md`
117
- - "Modify the URL of the website / change my project's address / connect a custom domain (e.g. blog.example.com) / rename the Fimo-provided `*.fimo.site` subdomain / buy a new domain through Fimo / set up a domain" → `references/domains.md`
118
- - "Invite a collaborator / add Marc / share with client" → `references/invite.md`
119
- - "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` changes the active **Fimo Branch** (see `references/branches.md`)
120
- - "Install Fimo for my agent / fimo skills install / set up Claude Code, Codex, or Cursor for Fimo" → `references/agent-setup.md`
121
- - "Refresh / update installed Fimo skills / fimo skills sync / agent missing the latest Fimo conventions" → `references/agent-setup.md`
122
- - "Update / upgrade the project's fimo packages / move to a new Fimo release / `fimo update`" → `references/update.md`. Never edit `fimo` or `fimo-*` versions directly in `package.json`; `fimo update` keeps package pins and codemods aligned.
123
- - "Report a Fimo problem or blocking feature request / contact Fimo support / a Fimo API or command keeps failing / a documented argument is rejected / a supported operation needs an undocumented workaround / a Fimo API is abnormally slow / a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround" → `references/support.md`
124
- - "Regenerate rule files / I edited AGENTS.md / fimo rules sync" → `references/agent-setup.md`
125
- - "Show analytics / visitor stats / traffic / pageviews / how is my site performing / top pages / where do visitors come from" → `references/analytics.md` (7-day preview free for all; longer ranges require paid)
126
- - "Mark a date on the analytics chart / annotate the chart with a deploy / add a launch note" → `references/analytics.md` § Annotations
127
-
128
- ## Lifecycle nudges
129
-
130
- These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
131
-
132
- - **Right after `fimo init`** → `cd` into the new directory, read the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code), run `fimo describe --json`, then load `fimo-code` and only the task/framework references it routes to. The rules file came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
133
- - **When `fimo init` created or scaffolded a new site (create-new path, including a Studio-supplied `--project-id`)** → after init and context loading succeed, run the single first-preview deploy and return the preview and dashboard links — see `references/init.md` § Create the first hosted preview. That deploy is also the sandbox warm-up; never run a separate warm-up deploy. Skip it only if the user explicitly said not to deploy. Linking a project with existing code and migrations keep their own approval rules.
134
- - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
135
- - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview on the create-new path, never as a blocker before initializing.
136
- - **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
137
- - **Optional, outside new-project onboarding (its first preview already warms the sandbox), if you already know a deploy is coming** → warm the sandbox early with `fimo deploy -m "chore: init" &` in the background so the one-time ~15-30s provision + dep install happens while you work and the real deploy lands warm (~4-10s). This is a perf optimization, not a requirement. See `references/deploy.md` § Warm the sandbox early in a session.
138
- - **You need the current preview URL but haven't changed code** (opening it, screenshotting it, handing it to another tool, the previous URL expired) → `fimo preview url`, never a no-op `fimo deploy`. See `references/preview.md`.
139
- - **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature Branch: `fimo checkout -b <name>` gives an isolated Branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
140
- - **After completing or safely preserving the user's main work, when a confirmed Fimo platform failure still materially blocks the task after one safe recovery attempt, or a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround** → use the built-in `supportReport` tool. Do not wait for the user to ask and do not stop after only describing the gap. See `references/support.md`.
141
- - **After the first successful `fimo deploy`** → suggest `fimo invite` if the project involves multiple people. Typical roles: `edit` for developers/content editors, `view` or `comment` for clients/stakeholders, `full` for project leads. See `references/invite.md`.
142
- - **After the automatic first-preview deploy on the create-new path, before the project has been published** → if there is no custom domain and the free default `*.fimo.site` slug still looks generated or was never explicitly chosen, offer to find a cleaner free subdomain. It needs no DNS. Never claim one without explicit user confirmation: suggest candidates, let the user choose, then rename it. Choosing the slug does not publish the site; the URL starts resolving only after the first successful `fimo deploy --publish`. Skip this nudge if the user already chose the default slug, attached a custom domain, or declined. See `references/domains.md` § Offer a cleaner default URL before first publish.
143
- - **When the user wants to modify the URL of their website** → walk through `references/domains.md`. The CLI surface covers renaming the Fimo-provided subdomain (`fimo domains rename-default`, free), attaching a domain they already own (`fimo domains add`, Premium), and buying a new domain through Fimo (`fimo domains buy`, Premium).
144
-
145
- ## Anti-Patterns
146
-
147
- - **Editing `.fimo/project.json`** — read-only; it's the link between local and remote site. Treat as a generated file.
148
- - **Treating `fimo deploy` as the working loop or a required final step** — the loop is local (`pnpm dev` etc.). Deploy commits + pushes + round-trips the sandbox; it's for hosted previews / going live, on-demand. Iterate locally and deploy at logical breakpoints. See `references/deploy.md`.
149
- - **Deploying without the developer asking or confirming** — new-project onboarding authorizes exactly one automatic first preview deploy (unless the user said not to deploy); every other deploy is offer-then-confirm. Don't auto-deploy after finishing an ordinary edit.
150
- - **Running `fimo deploy` just to get the current preview URL** — that's a commit + push + sandbox sync when only destination resolution is needed. Use `fimo preview url` instead. See `references/preview.md`.
151
- - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
152
- - **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
153
- - **Hardcoding content / strings / images in code, or committing image and video files** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's non-negotiable boundaries.
154
- - **Adding another deploy tool**. Fimo handles deploys; don't bolt another platform on.
155
- - **Committing secrets or storing API keys as public variables** — server-side keys use `fimo vars add --private`; Fimo-only credentials use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.
156
- - **Hardcoding tokens in flags** — use the credentials written by `fimo login` (one file per backend at `~/.config/fimo/credentials/<host>-<hash>.json`).
157
- - **Treating the daily allowance as extra credits** — the allowance section appears only for legacy Premium organizations, and `fimo credits` already includes its spendable credits in "Available now"; it is accounting context, not an amount to add.
158
- - **Trying to refill credits from the CLI** — `fimo credits` is read-only. Buying/refilling credits belongs in the billing UI for now.
27
+ ## Work loop
28
+
29
+ - Work locally: run the project's `dev` script in the background (`pnpm dev`, `npm run dev`, `yarn dev`, or `bun dev`, from the lockfile). Live reload shows each change. You do not need a deploy to see it.
30
+ - `fimo validate` runs all checks and codegen, and fails when default-locale labels are missing. It does not type check: also run the project's `typecheck` or `check` script. Keep `fimo validate --json` first in the `build` script.
31
+ - Keep editor content, copy, and media in schemas, labels, and the media library, not in code (`fimo-code`).
32
+ - Fimo hosts and deploys the site. Do not add another hosting or deploy tool.
33
+
34
+ ## Safety
35
+
36
+ - **Deploy:** `fimo deploy -m "<message>"` makes a hosted preview. Deploy only when the developer asks or agrees. When a unit of work looks done, offer a deploy. The only automatic deploy is the first preview after `fimo init` creates a site (`--ref init`).
37
+ - **Publish:** add `--publish` only when the user says to publish, ship, or go live. It makes the site public.
38
+ - **Preview URL:** when you need the current preview URL and the code did not change, run `fimo preview url`. Never deploy only to get a URL.
39
+ - **Secrets:** put server-side keys in `fimo vars add <NAME> --private`, and Fimo-only credentials in `fimo secrets`. Never commit secrets, put them in public variables, or pass tokens in flags. `fimo login` stores the session.
40
+ - **Packages:** change `fimo` and `fimo-*` versions only with `fimo update <version>`, never in `package.json`.
41
+ - **Blockers:** first finish or save the main work. Then, if a confirmed Fimo platform failure still blocks the task after one safe recovery step, or a missing capability blocks it or forces a fragile workaround, use the `supportReport` tool. Do not wait for the user to ask (`--ref support`).
42
+
43
+ ## Find the reference
44
+
45
+ Load a reference with `fimo skills get fimo-cli --ref <name>`. "+ fimo-code `<ref>`" means: also load that `fimo-code` reference and the reference for the detected framework.
46
+
47
+ - Create a site, link a project, `fimo init`, and the steps right after init → `init`
48
+ - No account or no browser: `fimo new <dir> --yes --json` (a person claims the site in 72 hours; `fimo claim --json` shows the link; `fimo new --instructions` prints the guide) → `account`
49
+ - Sign in, who am I, switch organization (`fimo orgs switch`; `fimo switch` changes the Branch) → `account`
50
+ - List, clone, rename, delete, or unpublish projects → `projects`
51
+ - Project snapshot: framework, schemas, routes, locales, tree (`fimo describe --json`) → `describe`
52
+ - Content types, Singles, entries, a blog, the CMS → `content` + fimo-code `content/schema`
53
+ - Page routes, params, and sources that Studio shows → `pages`
54
+ - Forms and form submissions → `forms` + fimo-code `forms`
55
+ - Upload, replace, or remove media files → `assets` + fimo-code `assets`
56
+ - Generate or edit an image or video with AI → `media` (+ fimo-code `assets` to show it in the UI)
57
+ - Labels, static copy, missing `t()` values → `labels` + fimo-code `labels`
58
+ - Locales and the default locale → `locales` + fimo-code `locales`
59
+ - Deploy, publish, a failed deploy or publication, blocked build scripts, markdown pages for AI agents → `deploy`
60
+ - Preview URL → `preview`
61
+ - Redirects, security headers, clean URLs, trailing slash → `hosting`
62
+ - Broken links, SEO, alt text, accessibility, Web Vitals, console errors in a browser → `site-checks`
63
+ - Branches: create, switch, status, diff, merge into `main`, pull. Suggest a Branch for a risky change (`fimo checkout -b <name>`) → `branches`
64
+ - Restore points and recovery → `history`
65
+ - Environment variables and secrets → `project-vars-and-secrets`
66
+ - Send form submissions, publishes, or other events to Slack, Resend, GitHub, Zapier, or a URL → `webhooks`
67
+ - Connected apps, Search Console, Google Analytics, MCP servers → `integrations`; Firecrawl web research → also `integrations/firecrawl`
68
+ - Visitors, page views, top pages, chart annotations → `analytics`
69
+ - Site URL: rename the free `*.fimo.site` slug (`fimo domains rename-default <slug>`), add a domain the user owns, buy a domain → `domains`
70
+ - Invite people. After the first deploy, suggest it when other people work on the site → `invite`
71
+ - AI credit balance (read-only) → `credits`
72
+ - Scheduled commands → `schedules`
73
+ - Set up an AI agent, install or sync Fimo skills, `fimo rules sync` → `agent-setup`
74
+ - Update Fimo packages → `update`
75
+ - Report a Fimo problem → `support`
76
+ - Move an existing site or app onto Fimo (published URL, source code, export, CSV files, `fimo link`) → load the `fimo-migration` skill
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: fimo-cli
3
+ description: >-
4
+ Operate a Fimo site through the `fimo` tool: content, Singles, schemas,
5
+ forms and their submissions, media and AI images, labels and locales, pages,
6
+ analytics, domains, webhooks, schedules, site checks and history. Read the
7
+ matching reference before the first command in a domain.
8
+ ---
9
+
10
+ # Fimo CLI
11
+
12
+ The `fimo` tool runs each command for you, on this project's Fimo version and on the version of the site you are working on, and returns the CLI's JSON. Fimo serves the preview, so there is nothing to install, start or deploy. Code in the project (schema JSON, generated clients, primitives, framework adapters) is the `fimo-code` skill. For one command's flags, run it with `--help`.
13
+
14
+ ## Every task
15
+
16
+ - **Site knowledge:** before planning, recommendations, design, copy, content, or code work, read `knowledge get`. Rules: reference `knowledge`.
17
+ - **Output:** read `data`. Branch on `error.code`, not on the message, and follow `hint`. Commands never prompt, so give each answer as a flag (`--yes`).
18
+ - **Content lives in Fimo:** editor content, copy and media go in schemas, labels and the media library, not in code, so people can change them in Studio without you (`fimo-code`).
19
+
20
+ ## Find the reference
21
+
22
+ Load a reference with `skillLoad` (`fimo-cli`, reference `<name>`). "+ fimo-code `<ref>`" means: also load that `fimo-code` reference and the reference for the project's framework.
23
+
24
+ - Project snapshot: framework, schemas, routes, locales, tree (`describe`) → `describe`
25
+ - Content types, Singles, entries, a blog, the CMS → `content` + fimo-code `content/schema`
26
+ - Page routes, params, and the sources Studio shows for a page → `pages`
27
+ - Forms and form submissions → `forms` + fimo-code `forms`
28
+ - Upload, replace, or remove media files → `assets` + fimo-code `assets`
29
+ - Generate or edit an image or video with AI → `media` (+ fimo-code `assets` to show it on the site)
30
+ - Labels, static copy, missing `t()` values → `labels` + fimo-code `labels`
31
+ - Locales → `locales` + fimo-code `locales`
32
+ - Preview URL → `preview`; a preview that fails to build, and its logs → `deploy`
33
+ - Redirects, security headers, clean URLs, trailing slash → `hosting`
34
+ - Broken links, SEO, alt text, accessibility, Web Vitals, console errors in a browser → `site-checks`
35
+ - Restore points → `history`
36
+ - Send form submissions, publishes, or other events to Slack, Resend, GitHub, Zapier, or a URL → `webhooks`
37
+ - Firecrawl web research and Fal media → `integrations/firecrawl`, `integrations`
38
+ - Visitors, page views, top pages, chart annotations → `analytics`
39
+ - Site URL: the free `*.fimo.site` slug, a domain the person owns, buying a domain → `domains`
40
+ - Scheduled commands → `schedules`
41
+ - Report a Fimo problem → `support`
42
+ - Move an existing site or app onto Fimo → load the `fimo-migration` skill
@@ -1,126 +1,63 @@
1
- # Branches (git-shaped workflow)
1
+ # Branches
2
2
 
3
- > **Beta:** Branches are still in beta. The CLI surface is available for early workflows, but not every command or cross-surface merge path is guaranteed to work reliably yet.
3
+ Branches are in beta: some commands and cross-surface merges can still fail.
4
4
 
5
- A Fimo **Branch** is a multi-surface clone of the project: a git branch **plus** its own Neon DB branch, sandbox, preview URL, and R2 asset prefix. The CLI mirrors `git` command shapes so the workflow transfers directly — same verbs, multi-surface semantics. In Project Settings, an **Environment** is a grouping policy such as Production or Preview; it is not this Branch-backed clone.
5
+ A Fimo **Branch** is a Git branch plus its own database, preview sandbox, preview URL, and asset prefix. The commands copy `git` verbs. An **Environment** in Project Settings (Production, Preview) is a policy that groups Branches; it is not a Branch.
6
6
 
7
- New standalone projects start with one Branch: `main`. Linking an unversioned folder, cloning, and scaffolding read the project's default Branch from Fimo when they set up Git. You create more for feature work, deploy previews per Branch, then merge back and publish.
7
+ ## Which Branch a command uses
8
8
 
9
- ## The Branch model — how every command picks its target
10
-
11
- **This is the single most important concept: site-scoped commands target the Branch matching the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` Branch's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which Branch it resolved.
12
-
13
- ```bash
14
- fimo --branch <name> <command> # peek at another Branch for one command (does not switch)
15
- ```
16
-
17
- - **`--branch <name>`** is the canonical global override. `fimo --branch main status` inspects `main` while you stay checked out on your feature Branch.
18
- - **`--env <name>`** is not a Branch selector. It is rejected; use `--branch <name>`.
19
- - Git-changing commands use the current branch; cross-branch status only reports the mismatch.
20
- - If Git cannot name a Branch, the CLI stops instead of guessing. Check out a Branch or pass `--branch <name>`. Sandboxes receive their Branch through `FIMO_ENV`.
21
- - If the git branch maps to no Fimo Branch, the CLI errors with a hint (`fimo branch` to list, `fimo branch <name>` to create) rather than guessing.
22
- - The project's default Branch cannot be deleted. Existing standalone projects use **`main`**.
23
- - **`release/*`** Branches are **read-only** — they're tags produced by `fimo publish`, not branches you push to. `fimo deploy` refuses them.
24
- - **`prod`** is protected: it cannot be created, forked from, checked out, or deleted. It's updated by publishing, never by pushing.
9
+ - A site command uses the Fimo Branch that matches the current Git branch, and prints its name.
10
+ - `fimo --branch <name> <command>` reads or writes another Branch for one command, without a switch. `--env` is not accepted. `deploy` and `pull` change Git, so they need the matching checkout: run `fimo checkout <name>` first.
11
+ - If Git names no branch (detached HEAD) and you pass no `--branch`, or the Git branch has no Fimo Branch, the CLI stops with a hint. It does not guess.
12
+ - **Protected:** the default Branch (`main`) cannot be deleted. A checkout of a `release/*` tag is read-only. `prod` cannot be created, forked, checked out, or deleted; only a publish changes it.
25
13
 
26
14
  ## Commands
27
15
 
28
- | Command | git analogue | What it does |
29
- | ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
- | `fimo branch` | `git branch` | List Branches (current marked `*`). `-v` includes deleted Branches. |
31
- | `fimo branch <name>` | `git branch <name>` | Create a Branch off the current one. `--from <branch>` forks from a different parent. Provisions DB + sandbox + preview + R2 prefix. |
32
- | `fimo branch -d <name>` | `git branch -d` | Delete a Branch — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`. |
33
- | `fimo checkout <name>` | `git checkout` | Switch to a Branch (checks out the matching git branch; the app derives its Branch from that branch at startup). `-b` creates + switches; `--from <branch>` sets the parent. |
34
- | `fimo switch <name>` | `git switch` | Switch to an existing Branch. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch. |
35
- | `fimo pull` | `git pull` | Fast-forward the local checkout to the Branch's latest code on Fimo. Never changes the Branch on the server. |
36
- | `fimo diff [from] [to]` | `git diff` | Two-Branch diff across all surfaces. Defaults `from` = current Branch, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`. |
37
- | `fimo status` | `git status` | Multi-surface status for the current Branch vs its parent. See below. |
38
- | `fimo merge <from>` | `git merge` | Merge another Branch into the current one (multi-surface, atomic, interactive conflict resolver). See below. |
39
- | `fimo publish` | — | Publish the revision already on the Fimo remote (no push) with a stable Fimo publication ID. See "Publishing" below. |
40
-
41
- All of these accept the global `--branch` override. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
42
-
43
- > **`fimo switch` changes the active Fimo Branch, not the org.** A Fimo Branch keeps its code, database, sandbox, content, and preview together. To change your active organization, use `fimo orgs switch` — see `references/account.md`.
44
-
45
- ## The 6 surfaces
46
-
47
- `status`, `diff`, and `merge` all reason over the same per-Branch surfaces, in this order:
48
-
49
- `code` · `schemas` · `content` · `translations` · `assets` · `forms`
50
-
51
- `--surface <name>` on `diff` and the per-surface flags on `status` (`--code`, `--content`, `--i18n`, `--agents`, `--assets`, `--forms`) filter to one of them.
52
-
53
- ## Typical PR-style flow
54
-
55
- ```bash
56
- fimo checkout -b feat/seo # branch off main: git branch + Branch provisioned
57
- # …generate / edit code, schemas, content, translations…
58
- fimo deploy -m "feat: seo pass" # deploy a preview of the feat/seo Branch
59
- fimo preview url # canonical URL to open / screenshot the feat/seo preview
60
- fimo status # see what changed vs main, surface by surface
61
- fimo checkout main # back to main
62
- fimo merge feat/seo # merge the Branch back into main (resolve conflicts)
63
- fimo publish --label "Homepage launch" --notes "Initial production publish"
64
- fimo branch -d feat/seo # tear down the feature Branch
65
- ```
66
-
67
- ## `fimo status`
68
-
69
- The showcase command — a unified, color-coded report of what's changed on the current Branch, grouped by surface, with per-surface counts.
70
-
71
16
  ```bash
72
- fimo status # full report, current Branch vs parent (or main)
73
- fimo status --short # one line per surface
74
- fimo status --vs main # compare against an explicit Branch
75
- fimo status --content # only the content surface (combine flags freely)
76
- fimo status --json # machine-readable
17
+ fimo branch [-v] [--all] # list (-v: deleted too; --all: agent task/* Branches too)
18
+ fimo checkout -b <name> [--from <branch>] # create a Branch from the current one (or --from) and switch to it
19
+ fimo checkout <name> # switch; `fimo switch <name>` is the same (no -b)
20
+ fimo branch <name> [--from <branch>] # create without a switch
21
+ fimo branch -d <name> # delete: removes its sandbox, database, and assets
22
+ fimo status [--vs <branch>] [--short] [--code|--content|--i18n|--assets|--forms] --json
23
+ fimo diff [from] [to] [--surface <name>] --json # from = current Branch, to = its parent (else main)
24
+ fimo merge <from> [-y] [--resume] [--allow-direct-merge] --json
25
+ fimo pull # fast-forward this checkout to the Branch on Fimo
77
26
  ```
78
27
 
79
- - The **code** surface is computed from your local git workspace (`git status --porcelain`), so uncommitted edits show up immediately.
80
- - Each surface has a soft timeout — a slow surface renders as timed-out rather than blocking the whole report.
28
+ - **Create Branches with `fimo`, not `git checkout -b`.** Raw Git makes no database, sandbox, or preview. If that happened, run `fimo branch <name> --from <parent>` to add them.
29
+ - `fimo switch` changes the Branch. `fimo orgs switch` changes the organization.
30
+ - `status`, `diff`, and `merge` compare six surfaces: `code`, `schemas`, `content`, `translations`, `assets`, `forms`. `status` also shows uncommitted local edits. A slow surface shows as timed out: treat it as unknown, not unchanged.
31
+ - Code reads its Fimo connection from the Git branch and `.fimo/project.json`. Do not hardcode the tenant API URL; an explicit host variable overrides that on every Branch.
32
+ - Deleting a Branch removes its data. Delete only a Branch that the user no longer needs.
81
33
 
82
- ## `fimo merge`
34
+ ## Typical flow
83
35
 
84
36
  ```bash
85
- fimo merge feat/seo # merge feat/seo into the current Branch
86
- fimo merge feat/seo -y # non-interactive: keep the target's value on every conflict
87
- fimo merge feat/seo --resume # continue a stopped merge, or follow one still applying
88
- fimo merge feat/seo --allow-direct-merge # override the "don't merge straight onto main" gate
37
+ fimo checkout -b feat/seo --from main # isolated Branch from main
38
+ fimo deploy -m "feat: seo pass" # hosted preview of feat/seo
39
+ fimo preview url # its preview URL
40
+ fimo status # what changed, surface by surface
41
+ fimo checkout main
42
+ fimo merge feat/seo --allow-direct-merge # only when the user asked to merge into main
43
+ fimo deploy --publish # only when the user says to go live (--ref deploy)
44
+ fimo branch -d feat/seo
89
45
  ```
90
46
 
91
- - Merging directly onto `main` is gated — the CLI refuses unless you pass `--allow-direct-merge`. Prefer merging on a branch and publishing.
92
- - On conflicts nothing is applied. In a terminal you get a resolver per row: **parent** (keep the target's value), **child** (take the source's value), **pick** (edit in `$EDITOR`), or **abort**. `-y` keeps the target's value for everything.
93
- - `--json` never prompts. Unresolved conflicts exit non-zero with `MERGE_CONFLICTS`; `error.details` carries `merge_id`, `from`, `to`, and `conflicts`. Re-run with `--resume --yes` to keep the target's values, or resolve interactively.
94
- - After resolutions are accepted the CLI waits for the merge: success is `status: "ok"` with the completed merge's `mergeId` and `summary` but no `applied` list (per-surface counts are only reported when a merge applies cleanly without conflicts); `MERGE_FAILED` and `MERGE_CANCELLED` are terminal; `MERGE_IN_PROGRESS` means it is still applying — run `--resume` to keep following it. `--resume` never resubmits a merge that is already applying.
95
-
96
- ## `fimo pull`
97
-
98
- Brings the current Branch's latest code from Fimo into the local checkout, like `git pull --ff-only fimo <branch>`. Run it before editing locally when the Branch may have changed elsewhere (Studio, an agent, a teammate's deploy). It only reads from Fimo: it never changes the Branch on the server. To bring `main` into a feature Branch, use `fimo merge main`.
99
-
100
- It never rebases, merges, or stashes local work. It stops instead:
101
-
102
- - `ENV_BRANCH_BEHIND_DIRTY` — the checkout is behind and has uncommitted changes. Commit or stash them, then run `fimo pull` again.
103
- - `ENV_BRANCH_DIVERGED` — local commits and remote commits both exist. Run `git pull --rebase fimo <branch>`, fix any conflicts, then `fimo deploy`.
104
- - `ENV_BRANCH_MISMATCH` — the git checkout is on another branch, or a detached HEAD. Run `fimo checkout <branch>`.
105
-
106
- `--json` returns `details.commits_pulled` and `details.head` (the checkout's commit afterwards).
107
-
108
- ## Publishing — `fimo publish` vs `fimo deploy --publish`
47
+ ## Merge
109
48
 
110
- Two different "go live" mechanisms — don't confuse them:
49
+ - **`fimo merge` into `main` stops with `PROTECTED_FLOW`** unless you add `--allow-direct-merge`. Add it only when the user asked to merge into `main`. Merges between other Branches need no flag.
50
+ - A merge with conflicts applies nothing. A terminal shows a resolver per conflict: keep the target (current Branch) value, take the source value, edit the value, or stop. `-y` keeps the target value for every conflict.
51
+ - `--json` never prompts. Conflicts exit with `MERGE_CONFLICTS`; `error.details` has `merge_id`, `from`, `to`, and `conflicts`. To keep the target values, run `fimo merge <from> --resume --yes`.
52
+ - After the answers are accepted, the CLI waits for the merge. Success is `status: "ok"` with the `mergeId`; per-surface counts (`applied`) appear only for a merge with no conflicts, so their absence is not a reason to retry. `MERGE_FAILED` and `MERGE_CANCELLED` are final. `MERGE_IN_PROGRESS` means it still applies: run `--resume` to follow it. `--resume` on a merge that still applies only follows it; it does not send it again.
53
+ - To bring `main` into a feature Branch, run `fimo merge main` on the feature Branch.
111
54
 
112
- - **`fimo publish [--label <text>] [--notes <md>]`** — publishes the revision already on the Fimo remote without pushing. Fimo assigns the immutable publication ID; labels and notes are optional annotations. `--skip-validate` is an operator override.
113
- - **`fimo deploy --publish`** — pushes the current Production source Branch and flips the project live. See `references/deploy.md`.
55
+ ## Pull
114
56
 
115
- Choose `fimo deploy --publish` when local changes need to go live; choose `fimo publish` when the remote revision is the intended release. Both only run from the configured Production source Branch. Existing projects use `main`.
57
+ `fimo pull` gets the Branch's latest code from Fimo, like `git pull --ff-only fimo <branch>`. Run it before you edit when Studio, an agent, or a teammate may have changed the Branch. It never changes the Branch on Fimo, and it never rebases, merges, or stashes:
116
58
 
117
- ## Anti-patterns
59
+ - `ENV_BRANCH_BEHIND_DIRTY`: commit or stash the local changes, then pull again.
60
+ - `ENV_BRANCH_DIVERGED`: run `git pull --rebase fimo <branch>`, fix conflicts, then `fimo deploy`. Never force-push.
61
+ - `ENV_BRANCH_MISMATCH`: Git is on another branch or a detached HEAD. Run `fimo checkout <branch>`.
118
62
 
119
- - **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the Branch's DB / sandbox / preview. Always use `fimo` for Branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
120
- - **Hardcoding the tenant API URL** — the framework runtime derives it from the
121
- git branch and `.fimo/project.json`. Use an explicit host variable only as a
122
- deliberate override, such as a local API; it then wins over derivation on
123
- every branch.
124
- - **Trying to push to or delete `prod` / `release/*`** — these are read-only/protected. Publish to update prod; never push.
125
- - **`fimo merge` straight onto `main` as a habit** — it's gated for a reason. Merge on a branch, then publish.
126
- - **Confusing `fimo switch` (Branch) with `fimo orgs switch` (org).**
63
+ `--json` returns `details.commits_pulled` and `details.head`.
@@ -0,0 +1,48 @@
1
+ # Bulk entry writes
2
+
3
+ Load this page to create, update, or delete many entries in one command, or to write entries from a JSON file. Bulk writes use the same validation, locale, reference, and content-change paths as single writes.
4
+
5
+ ```bash
6
+ fimo entries bulk-create <Type> (--body '<json-array>' | --file <path> | --stdin) [--upsert-by <field>]
7
+ fimo entries bulk-update <Type> (--ids <id1>,<id2> | --where '<json>') --body '<json>' [--locale <code>]
8
+ fimo entries bulk-update <Type> (--file <path> | --stdin) [--locale <code>] # file shape: bulk-update --help
9
+ fimo entries bulk-delete <Type> (--ids <id1>,<id2> | --where '<json>') [--locale <code>]
10
+ ```
11
+
12
+ ## Create
13
+
14
+ `bulk-create` takes an array of normal create bodies. `--body`, `--file`, and `--stdin` all take the same array:
15
+
16
+ ```bash
17
+ fimo entries bulk-create BlogPost --body '[{"data":{"title":"First"}},{"data":{"title":"Second"},"locale":"es"}]'
18
+ fimo entries bulk-create BlogPost --file posts.json
19
+ ```
20
+
21
+ ## Same change for many entries
22
+
23
+ `--body` is a normal update body. Select the entries with `--ids`, or with a `--where` filter (the `entries list` filter, `--ref content/entries`):
24
+
25
+ ```bash
26
+ fimo entries bulk-update BlogPost --ids <id1>,<id2> --body '{"data":{"status":"published"}}'
27
+ fimo entries bulk-update BlogPost --where '{"status":"draft"}' --body '{"data":{"status":"published"}}'
28
+ ```
29
+
30
+ ## A different change for each entry
31
+
32
+ Write the per-entry array that `fimo entries bulk-update --help` shows to a file, then run it without `--body`:
33
+
34
+ ```bash
35
+ fimo entries bulk-update BlogPost --file updates.json
36
+ ```
37
+
38
+ ## Delete
39
+
40
+ ```bash
41
+ fimo entries bulk-delete BlogPost --ids <id1>,<id2>
42
+ fimo entries bulk-delete BlogPost --where '{"archived":true}'
43
+ ```
44
+
45
+ ## Results and limits
46
+
47
+ - Requested IDs that do not exist do not stop the valid writes: the CLI prints a warning, and `--json` lists the IDs in `warnings` and in `data.meta.missing`.
48
+ - Each `bulk-create` or `bulk-update` request saves all of its entries or none. `bulk-create` sends 100 entries per request (`--chunk-size`, at most 1,000). When a later request fails, the earlier ones stay saved: retry with `--upsert-by <field>` so that saved entries are updated, not created again.
@@ -0,0 +1,54 @@
1
+ # Read and filter entries
2
+
3
+ Load this page to filter, sort, search, select fields, or populate references and media. Write commands are in `--ref content`.
4
+
5
+ ```bash
6
+ fimo entries list <Type> [--where <json>] [--sort [-]<field>] [--search <q>] [--fields <a,b>] [--populate <a,b>]
7
+ [--locale <code>] [--limit <n>=20] [--cursor <cursor>] [--all-pages]
8
+ fimo entries get <Type> <id> [--locale <code>] [--populate <a,b>]
9
+ fimo singles get <Type> [--locale <code>] [--populate <a,b>]
10
+ ```
11
+
12
+ ```bash
13
+ fimo entries list BlogPost --where '{"featured":true}' --sort -publishedAt
14
+ fimo entries list BlogPost --where '{"rank":{"$gte":3}}' --sort rank
15
+ fimo entries list BlogPost --where '{"__fimo":{"contentType":{"$eq":"BlogPost"}}}'
16
+ fimo entries list BlogPost --search "launch"
17
+ fimo entries list BlogPost --limit 10 --cursor <next-cursor> --sort title
18
+ fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publishedAt --limit 12
19
+ fimo entries list BlogPost --fields slug,title,author --populate author
20
+ ```
21
+
22
+ ## `--where`
23
+
24
+ - A JSON object keyed by schema field name. A plain value means equality and keeps its JSON type: `{"featured":true}`, `{"category":"react"}`.
25
+ - Operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, `$null`, as the field type allows.
26
+ - Fimo metadata is under `__fimo`. Only `__fimo.contentType` is filterable.
27
+ - A reference filter takes the target `id`: `{"author":"750e..."}`. On a to-many field, `$eq` and `$contains` mean "contains this target", `$in` means "contains any of these", `$ne` and `$nin` mean "contains none of these", and `$null: true` means empty or missing.
28
+ - You cannot filter polymorphic references yet: the command fails with a clear error.
29
+
30
+ ## `--sort`, `--fields`, `--search`, pages
31
+
32
+ - `--sort field` is ascending and `--sort -field` is descending. You cannot sort on reference fields.
33
+ - `--fields` is a comma-separated list for list payloads. The API always returns `id`, `entryId`, `documentId`, and `locale`; name only the other fields the view needs.
34
+ - Use `--limit`, `--cursor` (the `nextCursor` of the last page), and `--all-pages` for pages. `--offset` still works in old scripts.
35
+
36
+ ## `--populate`
37
+
38
+ - A comma-separated list of top-level reference, media, or blocks fields to embed. A blocks field populates every media value inside it. Nested paths such as `sections.image` and other field types return 400. Run `fimo schemas get <Type> --json` to see field names and types.
39
+ - Without `--populate`, a reference returns `{ "id": "..." }` and media returns the stored `{ "source", "id", "url", "alt" }`. With `--populate author,cover`, `author` returns the target entry in the requested locale, and `cover` also gets the current `name`, `mime`, `width`, and `height` of the asset.
40
+ - Populate does not choose which target fields return.
41
+ - A populated target that does not exist in the requested locale is `null`. Add `localeFallbacks=true` to get the best available locale variant instead; its `locale` field shows which one.
42
+ - Limits: 200 references in one to-many write, and 500 different populated documents per field in one request. Over a limit, the API returns 400.
43
+
44
+ ## Reference values
45
+
46
+ - A fixed reference field has `"target": "Author"`; add `"many": true` for to-many. Write it as `{"id":"<id>"}`, or an array of those. Use `null` or `[]` for empty.
47
+ - A polymorphic reference has `"targets": ["Post", "Product"]` (never both `target` and `targets`). Write it as `{"contentType":"Post","id":"<id>"}`. Populated values are full entries of mixed types, and generated hooks add `$type` to each one.
48
+ - References inside blocks use the same write shapes (`id`, `documentId`, or `slug` selectors), but you cannot populate or filter them.
49
+
50
+ ```bash
51
+ fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"id":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
52
+ ```
53
+
54
+ In generated app code, the same query uses `populate: ['author', 'contributors'] as const`. Let the generated client infer the result type. If you need a named type, use `BlogPostResult<TFields, TPopulate>` (fimo-code `content/clients`); writes use `BlogPostInput`.