fimo 2.10.1-staging.1 → 2.10.1-staging.2
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.
- package/assets/skills/fimo-cli/SKILL.md +57 -139
- package/assets/skills/fimo-cli/references/content/bulk.md +57 -0
- package/assets/skills/fimo-cli/references/content/entries.md +54 -0
- package/assets/skills/fimo-cli/references/content/localized.md +56 -0
- package/assets/skills/fimo-cli/references/content/schemas.md +29 -0
- package/assets/skills/fimo-cli/references/content/sql.md +64 -0
- package/assets/skills/fimo-cli/references/content.md +33 -272
- package/assets/skills/fimo-cli/references/forms.md +1 -1
- package/assets/skills/fimo-cli/references/init.md +1 -1
- package/assets/skills/fimo-cli/references/locales.md +2 -2
- package/assets/skills/fimo-studio/SKILL.md +8 -10
- package/dist/cli/bundle.json +1 -1
- package/dist/cli/index.js +6 -6
- package/package.json +8 -8
- package/templates/astro/package.json +3 -3
- package/templates/nextjs/package.json +4 -4
- package/templates/react-router/package.json +5 -5
- package/templates/sveltekit/package.json +3 -3
- package/templates/vite/package.json +5 -5
|
@@ -9,150 +9,68 @@ description: >-
|
|
|
9
9
|
|
|
10
10
|
# Fimo CLI
|
|
11
11
|
|
|
12
|
-
|
|
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
|
-
|
|
14
|
+
## Every task
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
fimo skills
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
fimo
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
-
|
|
91
|
-
-
|
|
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, failed deploys, 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, diff, merge, status, release. 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,57 @@
|
|
|
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>'
|
|
8
|
+
fimo entries bulk-update <Type> (--file <path> | --stdin)
|
|
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
|
+
`--file` and `--stdin` take an array of `{ "id", "body" }` records. Do not add `--body`:
|
|
33
|
+
|
|
34
|
+
```json
|
|
35
|
+
[
|
|
36
|
+
{ "id": "<id1>", "body": { "data": { "status": "published" } } },
|
|
37
|
+
{ "id": "<id2>", "body": { "data": { "featured": true } } }
|
|
38
|
+
]
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
fimo entries bulk-update BlogPost --file updates.json
|
|
43
|
+
cat updates.json | fimo entries bulk-update BlogPost --stdin
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Delete
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
fimo entries bulk-delete BlogPost --ids <id1>,<id2>
|
|
50
|
+
fimo entries bulk-delete BlogPost --where '{"archived":true}'
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Results and limits
|
|
54
|
+
|
|
55
|
+
- One request writes at most 1,000 entries.
|
|
56
|
+
- 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`.
|
|
57
|
+
- 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`.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Localized and shared content
|
|
2
|
+
|
|
3
|
+
Load this page to add a locale variant of an entry, or to work with fields or types that are the same in every language.
|
|
4
|
+
|
|
5
|
+
## Locale variants
|
|
6
|
+
|
|
7
|
+
Schemas are localized by default. Without `--locale`, a command uses the project default locale. To read, update, or delete another variant, pass `--locale`: an entry is its stable `id` plus a `locale`.
|
|
8
|
+
|
|
9
|
+
To add a variant of an existing entry, create it with the source entry's `documentId`:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
fimo entries list Story --where '{"slug":"spring-notes"}' --fields slug,title # gives "id" and "documentId"
|
|
13
|
+
fimo entries create Story --locale es --document-id <documentId> --body '{"data":{"title":"Notas de primavera"}}'
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
- The API validates the variant like a new entry: send every required field, shared ones too. A shared (`"i18n": false`) value applies to every locale, so send its current value.
|
|
17
|
+
- Keep a project single-locale unless the user asks for more languages. When the project has more locales, create and update each locale explicitly.
|
|
18
|
+
- To find missing or stale translations, use SQL (`--ref content/sql`).
|
|
19
|
+
|
|
20
|
+
## Non-localized types
|
|
21
|
+
|
|
22
|
+
For content that is the same in every locale, set `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to make locale variants. Raw API and CLI responses then omit `locale`; generated collection models add the active or default locale, with no per-locale variants. The schema root accepts no other `i18n` options.
|
|
23
|
+
|
|
24
|
+
## Shared fields in a localized type
|
|
25
|
+
|
|
26
|
+
Mark a field `"i18n": false` when its value is not translated, such as a price, a SKU, a product photo, or a reference to the same target. Without it, editors enter the value once per locale, and the values drift apart.
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"uid": "Product",
|
|
31
|
+
"name": "Products",
|
|
32
|
+
"fields": {
|
|
33
|
+
"title": { "type": "string" },
|
|
34
|
+
"description": { "type": "richtext" },
|
|
35
|
+
"sku": { "type": "string", "i18n": false, "unique": true },
|
|
36
|
+
"price": { "type": "number", "i18n": false },
|
|
37
|
+
"photo": { "type": "media", "i18n": false },
|
|
38
|
+
"brand": { "type": "reference", "target": "Brand", "i18n": false }
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
A write to a shared field through any locale changes it in every locale of the document:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
fimo entries update Product <id> --locale es --body '{"data":{"title":"Silla","price":120}}'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
This sets the Spanish title, and sets the price to `120` in every language. An update that does not name a shared field does not change it.
|
|
50
|
+
|
|
51
|
+
- Only top-level scalar and reference fields accept `i18n`. Fields inside `blocks` follow the locale of their entry, and the push rejects `i18n` on them.
|
|
52
|
+
- On a non-localized type, the flag has no effect.
|
|
53
|
+
- `"i18n": true` is the default. Do not write it.
|
|
54
|
+
- `localized` is not a valid key anywhere.
|
|
55
|
+
|
|
56
|
+
**Making a field with content shared deletes data** when the languages hold different values. The push keeps the default-locale value of each document and discards the others, with no prompt and no undo. Before you add `"i18n": false` to a field that has content, tell the user what happens. If you are not sure, check whether the languages differ.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Schema commands and changes
|
|
2
|
+
|
|
3
|
+
Load this page to change a schema that already has content, or to list, read, or delete schemas. The schema JSON itself is in fimo-code `content/schema`.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
fimo schemas push [<Type>] # create or update from src/schemas; no type pushes all
|
|
7
|
+
fimo schemas push <Type> --rename <old.path>=<new.path> # repeat --rename for each moved field
|
|
8
|
+
fimo schemas list
|
|
9
|
+
fimo schemas get <Type> [--json]
|
|
10
|
+
fimo schemas delete <Type>
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
- The command is `fimo schemas` (plural). There is no `fimo schema`.
|
|
14
|
+
- A push of all schemas sends them as one atomic batch, so types that reference each other, also in a cycle, can go in one push.
|
|
15
|
+
- A push never deletes a schema whose file is missing. Use `fimo schemas delete <Type>`.
|
|
16
|
+
- Blocks allow at most 7 nested levels, 40 variants in one `schema.oneOf`, and 200 items per blocks field (`min` and `max`).
|
|
17
|
+
|
|
18
|
+
## What a push does to existing content
|
|
19
|
+
|
|
20
|
+
Fimo migrates content on push. A failed push changes nothing.
|
|
21
|
+
|
|
22
|
+
- Adding an optional field and changing labels keep all content.
|
|
23
|
+
- A new required field fills its `default` only where existing values need it. When no default can satisfy the existing content, the push fails.
|
|
24
|
+
- Removing a nested field or a block variant removes only those values.
|
|
25
|
+
- `string` and `text` values convert both ways. Other type changes convert safe values and reject unsafe ones, with no change to the schema or entries.
|
|
26
|
+
- Lowering a blocks `max` trims items from the end. Raising `min` adds items from the blocks `default` templates.
|
|
27
|
+
- Changing a reference target clears its links.
|
|
28
|
+
- When a field moves to a new name, pass `--rename old.path=new.path` so the one-time migration keeps its values. The rename is not stored in the schema JSON.
|
|
29
|
+
- Collection to Single removes the entries of that type and cleans the references to them. Single to collection keeps its entry.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Read-only SQL over entries
|
|
2
|
+
|
|
3
|
+
Use `fimo entries query` when SQL is clearer than list filters, for example to group, count, or compare entries across types and locales.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
fimo entries query --sql "SELECT content_type, count(*) AS total FROM entries GROUP BY content_type"
|
|
7
|
+
fimo entries query --sql "SELECT document_id AS id, data->>'title' AS title FROM entries WHERE content_type = 'BlogPost' LIMIT 20"
|
|
8
|
+
fimo entries query --file query.sql
|
|
9
|
+
cat query.sql | fimo entries query --stdin
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Rules
|
|
13
|
+
|
|
14
|
+
- One `SELECT` statement that reads only the `entries` table. Common aggregate, JSON, text, date, and window functions work. It needs content view access.
|
|
15
|
+
- A query stops after five seconds and returns at most 1,000 rows.
|
|
16
|
+
- **Never use SQL for content writes.** The API rejects them, because a SQL write skips schema validation, locale and reference handling, content-change events, and webhooks. Use `entries create`, `entries update`, `entries delete`, or their bulk variants (`--ref content/bulk`).
|
|
17
|
+
- If a safe read needs a SQL function that is not available, tell the user which function is missing, and use the `supportReport` tool when that gap blocks the task. Do not work around it with a write.
|
|
18
|
+
|
|
19
|
+
## Columns
|
|
20
|
+
|
|
21
|
+
- `id`, `document_id`, `content_type`, `locale`, `slug`, `data`, `created_at`, `updated_at`. Fimo can add internal columns: select the columns you need, not `SELECT *`.
|
|
22
|
+
- Schema fields are in the JSONB `data` column, for example `data->>'title'`.
|
|
23
|
+
- `document_id` is the stable id that `fimo entries`, content tools, references, and the API use. `id` is the internal id of one locale variant.
|
|
24
|
+
- A localized entry has one row per locale, and all rows share one `document_id`. A non-localized entry has `locale` null.
|
|
25
|
+
- When results feed another Fimo command, select `document_id AS id`, and use `locale` to choose a variant.
|
|
26
|
+
|
|
27
|
+
## Examples
|
|
28
|
+
|
|
29
|
+
English blog posts that have no Spanish variant:
|
|
30
|
+
|
|
31
|
+
```sql
|
|
32
|
+
SELECT source.document_id AS id, source.data
|
|
33
|
+
FROM entries source
|
|
34
|
+
WHERE source.content_type = 'BlogPost'
|
|
35
|
+
AND source.locale = 'en'
|
|
36
|
+
AND NOT EXISTS (
|
|
37
|
+
SELECT 1
|
|
38
|
+
FROM entries target
|
|
39
|
+
WHERE target.content_type = source.content_type
|
|
40
|
+
AND target.document_id = source.document_id
|
|
41
|
+
AND target.locale = 'es'
|
|
42
|
+
)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Spanish variants whose English source changed later:
|
|
46
|
+
|
|
47
|
+
```sql
|
|
48
|
+
SELECT
|
|
49
|
+
target.document_id AS id,
|
|
50
|
+
target.content_type,
|
|
51
|
+
target.slug,
|
|
52
|
+
source.updated_at AS source_updated_at,
|
|
53
|
+
target.updated_at AS target_updated_at
|
|
54
|
+
FROM entries source
|
|
55
|
+
JOIN entries target
|
|
56
|
+
ON target.content_type = source.content_type
|
|
57
|
+
AND target.document_id = source.document_id
|
|
58
|
+
WHERE source.locale = 'en'
|
|
59
|
+
AND target.locale = 'es'
|
|
60
|
+
AND source.updated_at > target.updated_at
|
|
61
|
+
ORDER BY source.updated_at DESC
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
These rows are possibly stale, not proof of a bad translation: the query shows only that the source changed later. Review the content, and use each row's `id` to update the variant.
|